PsL Monthly 1993 December

home *** CD-ROM | disk | FTP | other *** search

/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / basic / qbware.exe / QBWARE.DOC < prev next >

Wrap

Text File | 1990-11-30 | 211.9 KB | 8,366 lines

Q B W A R E THE QUICKBASIC INTERFACE LIBRARIES Version 1.30 R E F E R E N C E M A N U A L AJM Software P.O. Box 5303 Arvada, Co. 80005-0303 Copyright (c) AJM Software 1987, 1991 All Rights Reserved Introduction to QBWARE . . . . . . . . . . . . . . . . . . . 7 A Word about User-supported Software . . . . . . . . . . . . 8 WARRANTY . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Registration . . . . . . . . . . . . . . . . . . . . . . . . 10 Order Form . . . . . . . . . . . . . . . . . . . . . . . 11 Corporate and Quantity Purchases . . . . . . . . . . . 12 LICENSE . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Product Support . . . . . . . . . . . . . . . . . . . . . . . 14 Using QBWARE . . . . . . . . . . . . . . . . . . . . . . . . 15 BIOS Video Services . . . . . . . . . . . . . . . . . . . . . 18 BSVMODE - Get or set video mode . . . . . . . . . . . 19 BSVSCUR - Set or get cursor size . . . . . . . . . . . 19 BSVSWID - Get screen width . . . . . . . . . . . . . . 20 BSVSPOS - Get or set cursor position . . . . . . . . . 20 BSVSPAG - Get or set video display page . . . . . . . 21 BSVSCRUP - Scroll up or clear a window . . . . . . . . 22 BSVSCRDN - Scroll down or clear a window . . . . . . . 22 BSVRCHR - Read a character and attribute from the screen . . . . . . . . . . . . . . . . . . . . . . 23 BSVWCHR - Write a character to the screen . . . . . . 24 BSVWTTY - Write in teletype mode . . . . . . . . . . . 24 BIOS Keyboard Services . . . . . . . . . . . . . . . . . . . 25 BSKGET - Get a character from the keyboard . . . . . 26 BSKSTAT - Determine the status of the toggle keys . . 26 BSKCLR - Clear the keyboard buffer . . . . . . . . . 26 BSKNXT - Preview the keyboard buffer . . . . . . . . 27 BSKSTOG - Set keyboard toggles . . . . . . . . . . . . 27 BSKTOGH - Determine whether toggle keys are pressed . 27 BSCURS - Set cursor speed . . . . . . . . . . . . . . 28 BIOS Diskette Services . . . . . . . . . . . . . . . . . . . 29 BSDSTAT - Get diskette controller status . . . . . . . 30 BSDRESET - Reset floppy disk controller . . . . . . . . 31 BSDVRFY - Verify sectors on a disk . . . . . . . . . . 31 BSDREAD - Read a sector from a disk . . . . . . . . . 32 BSDWRIT - Write a sector to disk . . . . . . . . . . . 32 BSDFMT - Format a track on a disk . . . . . . . . . . 33 BIOS Miscellaneous Services . . . . . . . . . . . . . . . . 35 BSEQPMT - Get installed equipment . . . . . . . . . . 36 BSPINIT - Initialize printer . . . . . . . . . . . . . 36 Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 2 BSPSTAT - Get printer status . . . . . . . . . . . . . 37 BSPRINT - Print a string of characters . . . . . . . . 38 BIOS AT Disk Services . . . . . . . . . . . . . . . . . . . 39 BSDAPARM - Get current drive parameters . . . . . . . . 40 BSDATST - Test for drive ready . . . . . . . . . . . . 40 BSDARST - Alternate disk reset . . . . . . . . . . . . 40 BSDARCL - Recalibrate drive . . . . . . . . . . . . . 41 BSDADIAG - Perform controller diagnostics . . . . . . . 41 BSDASTAT - Detect diskette change . . . . . . . . . . . 41 BSDATYPE - Get disk type . . . . . . . . . . . . . . . 42 BSDASTYP - Set diskette type . . . . . . . . . . . . . 42 BSDASEEK - Position heads over a specified cylinder . . 43 File Attribute Services . . . . . . . . . . . . . . . . . . 44 FLGTIM - Get file creation time . . . . . . . . . . . 45 FLGDAT - Get file creation date . . . . . . . . . . . 45 FLGVOL - Get volume label . . . . . . . . . . . . . . 46 FLPDAT - Change file creation date and time . . . . . 46 FLPVOL - Change volume label . . . . . . . . . . . . 47 FLATTR - Change file attributes . . . . . . . . . . . 47 File Access Services . . . . . . . . . . . . . . . . . . . . 50 FLSET - Set number of available file handles . . . . 51 FLOPEN - Open a file . . . . . . . . . . . . . . . . 51 FLCLOS - Close a file . . . . . . . . . . . . . . . . 52 FLREAD - Read a record from a file . . . . . . . . . 52 FLWRIT - Write a record to a file . . . . . . . . . . 53 FLPOINT - Point to a specific record in a file . . . . 54 FLCREAT - Create a file . . . . . . . . . . . . . . . 54 FLDELETE - Delete a file . . . . . . . . . . . . . . . 55 FLRSECT - Read a sector . . . . . . . . . . . . . . . 56 FLWSECT - Write a sector . . . . . . . . . . . . . . . 56 DOS Replacement Services . . . . . . . . . . . . . . . . . . 58 FLFIND - Find a file or group of files . . . . . . . 59 FLCNT - Count the number of matching files . . . . . 59 FLMOVE - Move a file . . . . . . . . . . . . . . . . 60 FLCOPY - Copy a file to another file . . . . . . . . 60 FLSDRV - Set the current drive . . . . . . . . . . . 60 FLGDRV - Get the current drive . . . . . . . . . . . 61 FLCDIR - Change the current directory . . . . . . . . 61 FLGDIR - Get the current directory . . . . . . . . . 62 FLMDIR - Make a directory . . . . . . . . . . . . . . 62 FLDDIR - Delete a directory . . . . . . . . . . . . . 62 FLDSTAT - Retrieve disk statistics . . . . . . . . . . 63 Miscellaneous DOS Services . . . . . . . . . . . . . . . . . 64 BOOT - Initiate a cold or warm boot . . . . . . . . 65 DOSEXIT - Terminate with a return code . . . . . . . . . 65 Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 3 DOSEXEC - SHELL replacement . . . . . . . . . . . . . . 65 DOSCHOUT - Write a string to the standard output device . . . . . . . . . . . . . . . . . . . . . . . . . 66 DOSCHRIN - Read a character from the standard input device . . . . . . . . . . . . . . . . . . . . . . 66 DOSSTRIN - Read a string from the standard input device . . . . . . . . . . . . . . . . . . . . . . . . . 67 DOSRED - Redirect a DOS standard handle . . . . . . . 68 DOSPRSC - Print the screen . . . . . . . . . . . . . . 69 DOSVER - Get the DOS version . . . . . . . . . . . . 69 DOSVRFY - Turn verify mode on and off . . . . . . . . 69 The Print Spooler . . . . . . . . . . . . . . . . . . . . . 71 DOSPSTAT - Request spooler status . . . . . . . . . . . 72 DOSPCAN - Cancel all spooled files . . . . . . . . . . 72 DOSPDEL - Delete a file from the queue . . . . . . . . 72 DOSPLST - List all files in the queue . . . . . . . . 73 DOSPSUB - Submit a file to the queue . . . . . . . . . 74 String Functions . . . . . . . . . . . . . . . . . . . . . . 75 VERIFY - Verify all characters in a string . . . . . . 76 XVERIFY - Slightly different twist on VERIFY . . . . . 76 CHARXLAT - Replace multiple characters in a string . . 77 TRANSLAT - Replace all occurrences of a character in a string . . . . . . . . . . . . . . . . . . . . . . 78 COMPRESS - Remove leading and trailing blanks . . . . . 78 UPCASE - Convert all characters in a string to upper case . . . . . . . . . . . . . . . . . . . . . . . 79 LOCASE - Convert all characters in a string to lower case . . . . . . . . . . . . . . . . . . . . . . . 79 PROPER - Convert a string to a proper name . . . . . . 79 HEXSTR - Convert a string to its hexadecimal equivalent . . . . . . . . . . . . . . . . . . . . . . . . . 80 Date/Time Functions . . . . . . . . . . . . . . . . . . . . 81 DATEPACK - Pack a date into two bytes . . . . . . . . . 82 GREGTJUL - Convert a date from Gregorian to Julian format . . . . . . . . . . . . . . . . . . . . . . 83 JULTGREG - Convert a date from Julian to Gregorian format . . . . . . . . . . . . . . . . . . . . . . 83 DAYSDIFF - Compute the number of days between two dates . . . . . . . . . . . . . . . . . . . . . . . . . 83 WEEKDAY - Determine the day of the week . . . . . . . 84 CALENDAR - Pop-up a calendar anywhere on the screen . . 84 ADDTIME - Add two times together . . . . . . . . . . . 85 SUBTIME - Subtract two times . . . . . . . . . . . . . 85 Timer Services . . . . . . . . . . . . . . . . . . . . . 86 TIME . . . . . . . . . . . . . . . . . . . . . . . 86 TICKS . . . . . . . . . . . . . . . . . . . . . . 86 BSGETIME . . . . . . . . . . . . . . . . . . . . . 86 Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 4 Video Primitives . . . . . . . . . . . . . . . . . . . . . . 88 PUTLINE - Write a line of text to the video buffer . . 89 SAVESCR - Copy a window from the video buffer to memory . . . . . . . . . . . . . . . . . . . . . . 89 RESTSCR - Restore a window from memory to the video buffer . . . . . . . . . . . . . . . . . . . . . . 90 INPWIN - Get input from the keyboard . . . . . . . . 91 COLORLIN - Change the color of a window . . . . . . . . 91 Window Routines . . . . . . . . . . . . . . . . . . . . . . 93 PUTWIND - Pop up a window on the screen . . . . . . . 94 PUSHWIN - Copy a window from the video buffer to the screen stack . . . . . . . . . . . . . . . . . . . 94 POPWIN - Copy a window from the window stack to the video buffer . . . . . . . . . . . . . . . . . . . 94 INITWIN - Initialize windowing environment parameters . . . . . . . . . . . . . . . . . . . . 95 DEFWIN - Define individual window parameters . . . . 96 CNGWIN - Change window parameters . . . . . . . . . . 97 MOVEWIN - Move a window to a different part of the screen . . . . . . . . . . . . . . . . . . . . . . 98 POPTEXT - Display an array of text within a window . . 98 POPFTEXT - Display a formatted text window . . . . . . 99 COLORWIN - Recolor a window . . . . . . . . . . . . . . 100 Input Routines . . . . . . . . . . . . . . . . . . . . . . . 101 INCHAR - Accept input of a string of characters . . . 102 INDATE - Accept date input . . . . . . . . . . . . . 103 INYES - Accept yes/no input . . . . . . . . . . . . 104 INMF - Accept male/female input . . . . . . . . . . 105 Menu Routines . . . . . . . . . . . . . . . . . . . . . . . 107 BARMENU - Provide a two line bar menu . . . . . . . . 108 BARMENU1 - Multi-line bar menu . . . . . . . . . . . . 108 BARMENU2 - Lotus-like bar menu . . . . . . . . . . . . 109 PULLDOWN - Display a pulldown menu . . . . . . . . . . 110 SCRLSLCT - Display a scrollable list of items for selection . . . . . . . . . . . . . . . . . . . . 110 Miscellaneous Routines . . . . . . . . . . . . . . . . . . . 112 PESORT - Sort a character array . . . . . . . . . . . . 113 FNMODULO - Find the modulus of a large number . . . . . 113 QBCHIP - Determine Processor and Co-Processor type . 113 Appendices . . . . . . . . . . . . . . . . . . . . . . . . . 115 Appendix A . . . . . . . . . . . . . . . . . . . . . . 115 Keyboard Scan Codes . . . . . . . . . . . . . . . 115 Appendix B . . . . . . . . . . . . . . . . . . . . . . 116 BASIC Colors . . . . . . . . . . . . . . . . . . . 116 Appendix C . . . . . . . . . . . . . . . . . . . . . . 117 Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 5 About Disks and Diskettes . . . . . . . . . . . . 117 APPENDIX D . . . . . . . . . . . . . . . . . . . . . . 122 Using the File Access Services . . . . . . . . . . 122 Appendix E . . . . . . . . . . . . . . . . . . . . . . 123 The Print Spooler . . . . . . . . . . . . . . . . 123 Appendix F . . . . . . . . . . . . . . . . . . . . . . . 125 QBWARE Windowing Routines . . . . . . . . . . . . 125 Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 6 Introduction to QBWARE QBWARE is a comprehensive set of callable routines that provide easy to use extensions to QuickBasic. The DOS subroutines are specifically designed to provide an easy to use interface between Quickbasic programs and certain DOS facilities that would normally be unavailable to a Quickbasic program. These include access to the DOS print spooler and memory management routines. It is very important to read the manual before using any of these services, as proper setup is important. The BIOS subroutines are specifically designed to provide an easy to use interface between Quickbasic programs and your computer's Basic Input/Output System (BIOS). The system BIOS is a collection of programs that control most of the fundamental processes or functions of your computer such as system startup or initialization, communications with peripheral devices such as video, disks, modems, printers, etc., handling of certain error conditions such as Ctrl-Break, Divide by zero, and others. Some of the services presented here are already provided in Quickbasic and many of them are not. They will provide you with a greater degree of control over the environment in which your program executes as well as performing these services much more quickly. The file management subroutines are specifically designed to provide an easy to use interface between Quickbasic programs and the DOS File Management services. DOS File Management services are a layer of software that sit between your program and the computer's diskette or hard drive. You must keep in mind that many of these routines interact with your computer's BIOS and have been designed and tested on IBM and COMPAQ computers. In order for them to function properly, your computer must be an IBM or Compatible. These functions have been tested with version 4 and version 4.5 of Quickbasic. Quickbasic is a registered trademark of Microsoft. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 7 A Word about User-supported Software User-supported software is a means for the computing community to receive quality software while directly supporting software authors. It is based on the ideas that: The value and utility of software is best assessed by the user on his or her own system. Only after using a program can one really determine whether it serves personal applications, needs and tastes. The creation of independent personal computer software can and should be supported by the computing community. Copying of programs should be encouraged, rather than restricted. The ease with which software can be distributed outside traditional commercial channels reflects the strength, rather than the weakness, of electronic information. Under the user supported concept, anyone may request a copy of a user-supported program by sending a blank, formatted disk to the program author together with an addressed, postage-paid return mailer. A copy of the program, along with documentation on disk, will be sent by return mail on the user's disk. The program carries a notice suggesting registration for the program. You should register if you are going to use the program on a regular basis. Regardless of whether you register and use the program, you are encouraged to copy and distribute the program for the private, non-commercial, trial use of others. User supported software is generally not public domain material; most programs of this nature carry a copyright notice. Rather, the author has licensed you to copy and use the program under certain conditions. Likewise, user supported software is not intended to be free software; it is an experiment in economics, not altruism. It is intended to provide quality software at a low price, while directly supporting the author, without the overhead of distributors, dealers and advertising that produces $500 software packages. User supported software is having a hard time. More and more packages are being taken out of this market, and offered as more traditional, and expensive, products. The reason for this is simple: lots of people are using the packages but very few are paying for them. And without the support of the users, there is absolutely no incentive for software authors to provide their programs in this fashion. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 8 There are many good reasons to register. Besides supporting the author (that is, paying for the software you use), you generally get better support and receive mailed notification of updates and other products. In conclusion, if you regularly use a user supported program (sometimes called Freeware or Shareware) and have not sent in a registration to the author, please do so now. Only through the financial support of users will this kind of inexpensive software continue to be available. WARRANTY AJM Software makes no warranty of any kind, express or implied, including without limitation, any warranties of merchantability and/or fitness for a particular purpose. AJM Software shall not be liable for any damages, whether direct, indirect, special or consequential arising from a failure of this program to operate in the manner desired by the user. AJM Software shall not be liable for any damage to data or property which may be caused directly or indirectly by use of the program. IN NO EVENT WILL AJM Software BE LIABLE TO YOU FOR ANY DAMAGES, INCLUDING ANY LOST PROFITS, LOST SAVINGS OR OTHER INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF YOUR USE OR INABILITY TO USE THE PROGRAM, OR FOR ANY CLAIM BY ANY OTHER PARTY. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 9 Registration and ordering information A QBWARE registration licenses you to use the product on a regular basis. Registration includes mailed notification of updates and priority support. Users need register only one version of QBWARE - registration includes licensed use of all upgrades. Individual registrations for QBWARE are available from AJM Software at a cost of $39.00. AJM will provide you with the most current release of QBWARE in both object and assembly source code form on 5 1/4 inch diskette or 3 1/2" diskette. The reference manual will also be included on the diskette. Registration entitles you to include any QBWARE routine in your applications for distribution without royalty. Including QBWARE in your applications without registration is strictly prohibited. Quantity discounts are available. Please see the section titled 'Corporate and quantity purchases'. In addition, evaluation disks are available at any time for $10. These disks do not include registration. The fee covers diskette, postage and handling. Please use the enclosed order form when placing an order. ORDERS OUTSIDE THE US: Please include an additional $10.00 to cover additional postage and handling costs. No C.O.D.'s will be accepted on orders delivered outside the US. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 10 Remit to: AJM Software Order Form P.O. Box 5303 Arvada, CO 80005-0303 Please send: ____ QBWARE Disk (Evaluation only) ............. @ $ 10.00 ea $ ______ (includes all routines in .QLB form and manual on disk) ____ QBWARE Registration ....................... @ $ 39.00 ea $ ______ (includes QBWARE disk and source code) Subtotal ______ Please check appropriate version Less Discount <______> QB V4 ____ C.O.D. Fee ($5.00) ______ QB V4.5 ____ 3 1/2" Disk ($5.00) ______ Shipping and Handling (Outside of U.S. only) ______ Total $ ______ Payment by: ( ) Check ( ) C.O.D. [NO CREDIT CARDS] Name: ____________________________________________________________ Company: ____________________________________________________________ Address: ____________________________________________________________ : ____________________________________________________________ : ____________________________________________________________ Day Phone: _________________________ Eve: ___________________________ ORDERS OUTSIDE THE US: Please include an additional $10.00 to cover additional postage and handling costs. No C.O.D.'s will be accepted on orders delivered outside the US. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 11 Corporate and Quantity Purchases All corporate, business, government or other commercial users of QBWARE must be registered. We offer quantity discounts starting at the sixth copy. Orders in quantities of less than 50 units are handled as bulk purchases. Purchases of over 50 units may be handled as quantity purchases or as corporate licensing agreements. Licensing agreements allow duplication and distribution of specific numbers of copies within the licensed institution. Duplication of multiple copies is not allowed except through execution of a licensing agreement. Please write for details. The quantity purchase discounts are as follows: 0- 5 copies: no discount 6- 20 copies: 20% discount 21+ copies: 40% discount ALL PRICES AND DISCOUNTS ARE SUBJECT TO CHANGE WITHOUT NOTICE. Discounts are not cumulative; they apply to single orders of like products only. Unit prices are the same as for individual users. WARNING: YOU MAY NOT USE QBWARE WITHIN YOUR ORGANIZATION WITHOUT A PRIOR PURCHASE OR LICENSE ARRANGEMENT. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 12 LICENSE All versions of QBWARE, including version 1.0, are not public domain software, nor are they free software. QBWARE is copyright (C) 1987, 1991 by AJM Software Non-registered users are granted a limited license to use QBWARE on a trial basis for the purpose of determining whether it is suitable for their needs. Use of QBWARE, except for this limited purpose, requires registration. Use of non-registered copies of QBWARE by any person, business, corporation, governmental agency or other entity institution is strictly forbidden. Registration permits a user the license to use QBWARE for development purposes, only on a single computer. QBWARE can be included into any program and distributed in library form only without royalty. A registered user may use the program on a different computer, but may not use the program on more than one computer at the same time. All users are granted a limited license to copy QBWARE only for the trial use of others subject to the above limitations, and also the following: QBWARE must be copied in unmodified form, complete with the file containing this license information. The full QBWARE documentation must be included with the copy. No fee, charge or other compensation may be accepted or requested by any licensee, except a handling fee not to exceed $10.00. QBWARE may not be distributed in conjunction with any other product. The ASSEMBLY source code for QBWARE may NOT be distributed under any circumstances. The object modules supplied with a registered copy of QBWARE may NOT be distributed under any circumstances. Operators of electronic bulletin board systems (Sysops) may post QBWARE for downloading by their users only as long as the above conditions are met. Distributors of public domain or user supported software, other than operators of electronic bulletin board systems, Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 13 may distribute copies of QBWARE subject to the above conditions only after obtaining written permission from AJM Software. Product Support If you have any questions or comments about the use of QBWARE, please fill out a problem log and send it to us. In your note, describe as completely as possible the problem you are having. Let us know your machine configuration, which routine you are questioning, the version of QBWARE, and any resident software installed. If possible, include a copy (on paper) of your source code. Describe what steps you take before the problem occurs, and exactly what the program does when it occurs. If you do not provide us with a complete description of the problem there is little we can do to help. We'll do our best to get you past the problem, but if you are not a registered user we do not guarantee to provide support of any kind. Please be patient. We usually respond to registered users within 3 working days at the most. We will provide support to non-registered users at our discretion. It generally depends on how the request is worded and the mental disposition of the staff person assigned to handle requests on that day. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 14 Using QBWARE QuickBasic versions 4, 4.5 All of the QBWARE routines can be accessed via the Quickbasic 'Call' statement. The format of this statement is as follows: Call Function(Parm1%, Parm2%, Parm3$) Function is the name of the routine to be executed. It must be spelled exactly as shown in the following chapters. The parameters to be passed to the routine will also be explained in the following chapters. You must use the exact number of parameters shown in each function description and each parameter must be the type (i.e. character or integer) shown in each function description. Using an incorrect number of parameters or using a parameter of the wrong type (i.e. using character instead of integer) will generally result in the abnormal termination of your program. Usually you will get either a 'String Space Corrupt' error or you will start executing the wrong statements in your program. In any event, it is almost impossible to predict the results of these two types of errors, so it is critical that you be very careful in coding the call statements. The parameters passed to QBWARE routines will be either character or numeric integers. There are no special requirements for passing integers and constants may also be used. There is no functional difference between these two sets of statements: Example 1 Drive$ = "A" 'Indicate drive a Vol$ = "DISK LABEL " 'New volume label Call FlPVol(Drive$, Vol$, Rc%) 'Call QBWARE routine Example 2 Call FlPVol("A", "DISK LABEL ", Rc%) Note that Rc% must not be defined as a constant because the QBWARE routine will return a value in this field and your Quickbasic program cannot access this field if it is defined as a constant. All character fields must be initialized to the proper length before calling a QBWARE function. Failing to do so may result in a 'String Space Corrupt' condition. The following two examples appear similar but Example 1 will fail and Example 2 will succeed because 'Char$' has been properly initialized. Example 1 (incorrect) Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 15 Char$ = "" 'clear work field Call FlGDrv(Char$) 'get the current drive Example 2 (correct) Char$ = space$(1) 'clear work field Call FlGDrv(Char$,) 'get the current drive Many of the Assembly Language routines require arrays to be passed to them. The only way to pass arrays and achieve consistent results is via the VARPTR function. Using VARPTR will ensure consistent results when using QBWARE routines from both the development environment and the DOS command line (NOTE that this applies only to the QBWARE Assembly language routines - QBWARE routines written in Quickbasic do not require that arrays be passed in this manner). For Example: Call FlFind(Count%, VARPTR(DirList$(LBound(DirList$)))) Using VARPTR will insure compatibility in compiling from within the QB4 environment and from the DOS prompt. You can use QBWARE routines within the Quickbasic development environment. This is done by starting QuickBasic as follows: QB /L QBWARE Make sure that the file QBWARE.QLB is in the current directory. This automatically loads the QBWARE quick library into the QB4 environment. Sample batch files are provided on the distribution disks (registered users only) to compile your Quickbasic programs. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 16 PRECAUTIONS!!!!!! These routines were designed to used with Quickbasic on an IBM PC or compatible computer. Using this product with any Basic compiler or interpreter other than Quickbasic version 4 or 4.5 will probably not work and may cause loss of data. Using this product on a non-IBM compatible computer will give hit or miss results. Some things will work, some things won't work. The only way to find out is to try. A SPECIAL NOTE ABOUT HARD DISKS - there are many manufacturers and varieties of hard disks available for the IBM PC and compatible computer. Many of these hard disks work through the traditional BIOS functions and many provide their own proprietary software to function properly. These disks with proprietary software may not respond properly to some of the BIOS interface routines. IN ANY EVENT, DO NOT TEST ANY HARD DISK OR FLOPPY DISK ROUTINES WITHOUT FIRST BACKING UP YOUR DISK - REPEAT - DO NOT TEST ANY HARD DISK OR FLOPPY DISK ROUTINES WITHOUT FIRST BACKING UP YOUR DISK. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 17 The BIOS Video Services Function Summary BSVMODE - Get or set video mode BSVSCUR - Set or get cursor size BSVSWID - Get screen width BSVSPOS - Get or set cursor position BSVSPAG - Get or set video display page BSVSCRUP - Scroll up or clear a window BSVSCRDN - Scroll down or clear a window BSVRCHR - Read a character and attribute from the screen BSVWCHR - Write a character to the screen BSVWTTY - Write in teletype mode Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 18 BSVMODE - Get or set video mode Usage - Call BsVMode(Function%, Mode%) Function% 0 - set video mode 1 - get video mode Mode% (When Function% = 0, Mode% must be initialized to one of the following values. When Function% = 1, Mode% will return one of the following values.) Mode Type Adapter 0 40 X 25 B/W text CGA 1 40 X 25 16 color text CGA 2 80 X 25 B/W text CGA 3 80 X 25 16 color text CGA 4 320 X 200 4 color graphics CGA 5 320 X 200 4-Grey graphics CGA 6 640 X 200 B/W graphics CGA 7 80 X 25 B/W text MA(Monochrome) 8 160 X 200 16 color graphics PCjr 9 320 X 200 16 color graphics PCjr 10 640 X 200 4 color graphics PCjr 10 640 X 200 16 color graphics EGA 13 320 X 200 4 color graphics EGA 14 640 X 200 16 color graphics EGA 15 640 X 350 4 color graphics EGA 16 640 X 350 4 or 16 color graphics EGA Programming notes: For RGB monitors, there is no functional difference between modes 0 and 1, or between modes 2 and 3. The EGA will support all modes except 8 and 9. Normally, the screen buffer will be cleared when you set the video mode - even if you set it the same mode. This is not, however, a recommended method for clearing the screen as it could cause some delay in many PC- compatibles. Using a mode that is not supported by your video adapter card will have unpredictable results. BSVSCUR - Set or get cursor size Usage - Call BsVSCur(Function%, Start%, End%) Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 19 Function% 0 - set cursor size 1 - get cursor size Start% Starting scan line End% Ending scan line Programming notes: The scan line is a row of pixels that make up a character on the screen. On monochrome monitors, there are 13 scan lines numbered 0 thru 12. On RGB monitors, there are 8 scan lines numbered 0 thru 7. The default val ues for cursor size are as follows: Mode Display Start End 0-3 RGB Monitor (text modes) 6 7 7 Monochrome 11 12 The hardware causes the cursor to blink and it normally cannot be dis abled while in text mode, however, some machines will cause the cursor to disappear when a starting scan line of 32 is used. A technique that always makes the cursor disappear is to move it off the screen using BSVSPOS (e.g. move it to column 1, row 26). Using a starting scan line that is greater than the ending scan line will make the cursor wrap and cause a two-part cursor to show on the screen. Function% must be initialized prior to calling BSVSCUR. If function% is 0 then Start% and End% must be initialized to proper values prior to making the call. BSVSWID - Get screen width Usage - Call BsVSWid(Wid%) Wid% Number of characters that can be displayed on the screen - either 40 or 80. BSVSPOS - Get or set cursor position Usage - Call BsVSPos(Function%, Row%, Column%, Page%) Function% 0 - set cursor position 1 - get cursor position Row% Cursor coordinate Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 20 Column% Cursor coordinate Page% Display page whose cursor position is to be set or retrieved. Programming notes: A separate cursor is maintained for each display page (See BSVSPAG for more on display pages). The cursor is affected only in the display page specified. Coordinates (1,1) represent the upper left hand corner of the screen. Coordinates (80,25) represent the lower right-hand corner of the screen. Positioning the cursor outside the limits of the current display will cause the cursor to disappear. In graphics modes, Row% and Column% should be interpreted as pixel coordi nates. Function% and Page% must be initialized prior to calling BSVSPOS. If Function% is 0 then Row% and Column% must be initialized prior to making the call. BSVSPAG - Get or set video display page Usage - Call(BsVSPag(Function%, Page%) Function% 0 - set current page 1 - get current page Programming Notes: Valid page ranges are as follows: Page range Mode Adapter 0 - 7 0 CGA 0 - 7 1 CGA 0 - 3 2 CGA 0 - 3 3 CGA 0 - 7 2 EGA 0 - 7 3 EGA 0 - 7 13 EGA 0 - 3 14 EGA 0 - 1 15 EGA 0 - 1 16 EGA Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 21 Changing pages has no effect on their contents and text can be written to any page regardless of which page is active. Using multiple pages is not possible on a monochrome monitor with an MDA adapter. Function% must be initialized to 0 or 1 prior to calling BSVSPAG. If Function% is 0 then Page% must be initialized to a valid page number. BSVSCRUP - Scroll up or clear a window Usage - Call BsVScrup(Lines%, FgColor%, BgColor%, Ulc%, Ulr%, Lrc%, Lrr%) Lines% Number of lines to scroll up. If Lines% is zero, then the entire window is blanked. FgColor% Foreground color - 0 thru 31 are valid foreground colors. BgColor% Background color - 0 thru 7 are valid background colors. Ulc% Coordinate of the left column of the scroll window. 1 indicates the far left column. Ulr% Coordinate of the top row of the scroll window. 1 indi cates the top row of the screen. Lrc% Coordinate of the right column of the scroll window. 80 is the far right column. Lrr% Coordinate of the bottom row of the scroll window. 25 is the last row of the screen. Programming notes: This function affects only the currently active display page and any data scrolled off of the window is lost. Blank lines are inserted at the bot tom of the window. If the number of lines to scroll equals zero, then the entire window is blanked out. All fields must be initialized prior to calling BSVSCRUP. BSVSCRDN - Scroll down or clear a window Usage - Call BsVScrdn(Lines%, FgColor%, BgColor%, Ulc%, Ulr%, Lrc%, Lrr%) Lines% Number of lines to scroll down. If Lines% is zero, then Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 22 the entire window is blanked. FgColor% Foreground color - 0 thru 31 are valid foreground colors. BgColor% Background color - 0 thru 7 are valid background colors. Ulc% Coordinate of the left column of the scroll window. 1 indicates the far left column. Ulr% Coordinate of the top row of the scroll window. 1 indi cates the top row of the screen. Lrc% Coordinate of the right column of the scroll window. 80 is the far right column. Lrr% Coordinate of the bottom row of the scroll window. 25 is the last row of the screen. Programming notes: This function affects only the currently active display page and any data scrolled off of the window is lost. Blank lines are inserted at the top of the window. If the number of lines to scroll equals zero, then the entire window is blanked out. All fields must be initialized prior to calling BSVSCRDN. BSVRCHR - Read a character and attribute from the screen Usage - Call BsVRChr(Char$, FgColor%, BgColor%, Row%, Col%, Page%) Char$ Character read from the screen. FgColor% Foreground color BgColor% Background color Row% Coordinate of the character to read from the screen. Col% Coordinate of the character to read from the screen. Page% Display page to read Programming notes: Char$ should be initialized to a single space prior to using this service. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 23 BSVWCHR - Write a character to the screen Usage - Call BsVWChr(Char$, FgColor%, BgColor%, Row%, Col%, Page%) Char$ Character to write to the screen. FgColor% Foreground color BgColor% Background color Row% Coordinate of the character to write to the screen. Col% Coordinate of the character to write to the screen. Page% Display page to be written to Programming notes: All fields should be properly initialized before using this service. The current cursor position is not affected by this service. BSVWTTY - Write in teletype mode Usage - Call BsVWTTY(Text$, FgColor%, BgColor%) Text$ Text to be written to the screen. FgColor% Foreground Color BgColor Background color Programming notes: This service recognizes special ASCII codes for bell, line feed, and back space. Any other characters are written to the screen and the cursor position is advanced appropriately. Do not mix this service with BASIC PRINT statements as the cursor posi tioning will be inconsistent. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 24 The BIOS Keyboard Services Function Summary BSKGET - Get a character from the keyboard BSKSTAT - Determine the status of the toggle keys BSKCLR - Clear the keyboard buffer BSKNXT - Preview the keyboard buffer BSKSTOG - Set keyboard toggles BSKTOGH - Determine whether toggle keys are pressed BSCURS - Set cursor speed Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 25 BSKGET - Get a character from the keyboard Usage - Call BsKGet(Char$, Scancode%) Char$ The character entered at the keyboard. Scancode% The scan code of the character entered at the keyboard. A partial list of scancodes is provided in Appendix A. Programming notes: This function retrieves the next character in the keyboard buffer. If there is nothing in the buffer, it will wait until a character is ready and thereby suspend program execution. BSKNXT, discussed later, will allow you to peek into the keyboard buffer to determine if a key has been pressed without suspending the program. Char$ will either the standard ASCII code of the key pressed or CHR$(0) if a special key was pressed (i.e. the function keys, PgUp, Home, etc.). If Char$ is a CHR$(0), then Scancode% will indicate which key was pressed. See Appendix A for a list of scancodes. BSKSTAT - Determine the status of the toggle keys Usage - Call BsKStat(Insert%, Caps%, Num%, Scroll%, Alt%, Ctrl%, LShift%, RShift%) Programming notes: For Insert%, Caps%, Num%, and Scroll% - If the returned value is 1, then that mode has been toggled on (i.e. - Caps light is on). If the value returned is 0, then that mode has been toggled off. For Alt%, Ctrl%, LShift%, RShift% - If the returned value is 1, then that key is currently depressed. If the value is 0, then that key is not depressed. BSKCLR - Clear the keyboard buffer Usage - Call BsKClr Programming notes: BSKCLR is not passed any parameters, nor does it return any values. It Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 26 simply clears any keystrokes that have not been read into your program but are waiting in the keyboard buffer. BSKNXT - Preview the keyboard buffer Usage - Call BsKNxt(Char$, Scancode%, Rc%) Char$ The character entered at the keyboard. Scancode% The scan code of the character entered at the keyboard. A partial list of scancodes is provided in Appendix A. Rc% Return code 0 indicates that no key has been pressed. Return code 1 indicates that a key has been pressed. Programming notes: This function will not remove a character from the keyboard buffer. If the return code indicates that a character is in the buffer, you must use BSKGET to get the character out of the buffer. See notes for BSKGET and Appendix A. BSKSTOG - Set keyboard toggles Usage - Call BsKSTog(Insert%, Caps%, Num%, Scroll%) Programming notes: Each parameter must be initialized to 0 or 1. If the parameter is ini tialized to 1 then that toggle will be turned on. If the parameter is 0 then that toggle will be turned off. For example: Call BsKSTog(0,1,1,0) will turn CapsLock and NumLock on, and it will turn ScrollLock and Insert mode off. BSKTOGH - Determine whether toggle keys are pressed Usage - Call BsKTogH(Insert%, Caps%, Num%, Scroll%) Programming notes: Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 27 No parameters need to be initialized prior to making this call. If any of the returned values is 1, that indicates that the corresponding key is currently being held down. If any of the returned values is 0, that indi cates that the corresponding key is not currently being held down. Note that this function does not tell us the status of the toggle keys, only whether or not someone is physically pressing them at that moment. BSCURS - Set cursor speed Usage - Call BsCurs(Dlay%, Rate%) Dlay% 0 - 250 ms delay before repeat key is generated 1 - 500 ms delay 2 - 750 ms delay 3 - 1000 ms delay Rate% Can vary from 0 thru 31 with 0 causing a repeat rate of 30 cps and 31 causing a repeat rate of 2 cps. Programming Notes: This function will not work on an 8088/8086 (PC/XT) processor. It can be used to vary keyboard action from very fast (Dlay%=0, Rate%=0) to very slow (Dlay%=4, Rate%=31). Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 28 The BIOS Diskette Services Function Summary BSDSTAT - Get diskette controller status BSDRESET - Reset floppy disk controller BSDVRFY - Verify sectors on a diskette BSDREAD - Read a sector from a diskette BSDWRIT - Write a sector to diskette BSDFMT - Format a track on a diskette *********************** IMPORTANT ************************* Before using any of these functions, please read the documentation care fully and when testing your programs, please use blank diskettes. These functions will also work with a hard disk, so if you have a hard disk installed, please take extra precautions. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 29 BSDSTAT - Get diskette controller status Usage Call BsDStat(Rc%) Rc% Reason - Diskette drives only 0 Successful 1 Invalid function 2 Address mark not found 3 Write protect error 4 Sector not found 6 Diskette change detected 8 DMA failure 9 DMA boundary overrun 16 bad CRC: parity check 32 controller malfunction 64 seek failure - move to requested track failed 128 time out - drive did not respond (the door is open) Rc% Reason - Hard disk drives only 0 Successful 1 Invalid function 2 Address mark not found 4 Sector not found 5 Reset failed 7 Drive parameter activity failed 9 DMA boundary overrun 10 Bad block flag detected 16 Uncorrectable ECC data error 17 ECC corrected data error 32 controller malfunction 64 seek failure - move to requested track failed 128 time out - drive did not respond 170 Drive not ready 187 Undefined error occured 204 Write fault active 255 Sense operation failed Programming notes: This function always returns the status of the last disk operation. The messages normally seen when accessing a diskette with DOS, such as: Not ready error reading drive a Abort, Retry, Ignore will not be seen when using this function (and any other BIOS diskette function), therefore, you must always determine whether a disk operation Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 30 has failed or succeeded when using the BIOS disk services. BSDRESET - Reset floppy disk controller Usage - Call BsDReset Programming notes: This function resets the disk controller and prepares it for I/O. It will force the BIOS diskette support routines to recalibrate the disk drive's read/write head. It should be used only after an error is detected during a disk drive operation. BSDVRFY - Verify sectors on a disk Usage - Call BsDVrfy(Buffer$, Drive$, Head%, Track%, Sector%, Rc%) Buffer$ Not used for this function. Drive$ Letter designation for to drive containing the diskette to be verified. Head% Cylinder head Track% Track containing sector to be verified. Sector% Relative ID of the sector to be verified. Rc% Return code - see function BSDSTAT Programming notes: For 1.2 Meg drives, the diskette drive parameter table must reflect the type of media installed for correct operation. It is the responsibility of the programmer to ensure that the diskette drive parameter table is correct. Unpredictable results can occur otherwise (See BSDASTYP). This service will verify only a single sector with each call. If needed, the Assembler source can easily be modified to verify more than one sector (up to an entire track). The verify service reads the specified sector and insures that it passes the CRC check. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 31 See Appendix C - Miscellaneous diskette information. BSDREAD - Read a sector from a disk Usage - Call BsDRead(Buffer$, Drive$, Head%, Track%, Sector%, Rc%) Buffer$ The string where the data read from disk will be placed into. Drive$ Letter designation for to drive containing the disk to be read. Head% Cylinder head containing the track to be read. Track% Track containing sector to be read. Sector% Relative ID of the sector to be read. Rc% Return code - see function BSDSTAT Programming notes: It is the responsibility of the programmer to ensure that Buffer$ is long enough to hold the sector read from disk (usually 512 bytes). If it is not long enough, the results are unpredictable. Generally you will see a 'String Space Corrupt' message returned from BASIC. This service will read only a single sector with each call. If necessary, the Assembler source can easily be modified to read more than one sector (up to an entire track). See Appendix C - Miscellaneous diskette information. BSDWRIT - Write a sector to disk Usage - Call BsDWrit(Buffer$, Drive$, Head%, Track%, Sector%, Rc%) Buffer$ The string containing the data to be written to disk. Drive$ Letter designation for to drive containing the disk to be written Head% Cylinder head containing the track to be written. Track% Track containing sector to be written. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 32 Sector% Relative ID of the sector to be written. Rc% Return code - see function BSDSTAT Programming notes: When testing, first backup your diskette. It is very easy to inadver tently erase usable data or render a diskette unusable with this service. This service will always write a complete sector. If Buffer$ is shorter than the length of a sector (usually 512 bytes), the contents of the sec tor written will be unpredictable. This service will write only a single sector with each call. If needed, the Assembler source can easily be modified to write more than one sector (up to an entire track). See Appendix C - Miscellaneous diskette information. BSDFMT - Format a track on a disk Usage - Call BsDFmt(Buffer$, Drive$, Head%, Track%, Sector%, Rc%) Buffer$ The string containing the track format table (See Appen dix C). Drive$ Letter designation for to drive containing the diskette to be formatted. Head% Cylinder head containing the track to be formatted. Track% Track containing sector to be formatted. Sector% Number of sectors to be formatted. Rc% Return code - see function BSDSTAT Programming notes: For 1.2 Meg drives, the diskette drive parameter table must reflect the type of media installed for correct operation. It is the responsibility of the programmer to ensure that the diskette drive parameter table is correct. Unpredictable results can occur otherwise (See BSDASTYP). When testing, first backup your diskette. It is very easy to inadver tently erase usable data or render a diskette unusable with this service. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 33 This service will always format a complete track. If Sector% is less than the maximum number of sectors that can fit on that track, then the unfor matted sectors will no longer be available. If you format track 0 on a diskette with this service, the diskette will not be usable until a boot record is written to sector 0. If needed, the Assembler source code can be modified to write a boot record to the dis kette. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 34 The BIOS Miscellaneous Services Function Summary BSEQPMT - Get installed equipment BSPINIT - Initialize printer BSPSTAT - Get printer status BSPRINT - Print a string of characters BSPRTSC - Print screen Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 35 BSEQPMT - Get installed equipment Usage - Call BsEqpmt(RomDate$, RAM%, ExtRAM%, ExpRAM%, Printers%, RS232%, Floppies%, Gameport%, Disks%) RomDate$ ROM-BIOS revision date RAM% Amount, in Kilobytes, of installed RAM. ExtRAM% Amount, in Kilobytes, of extended memory. ExpRAM% Amount, in 16K pages, of LIMM expanded memory. Printers% Number of printer ports installed. Rs232% Number of serial ports installed. Floppies% Number of floppy disk drives installed. Gameport% Number of gameports installed. Disks% Number of hard disks installed. Programming notes: Some of these fields may not be reliable in certain hardware configura tions. Items to be wary about are RomDate$, ExtRAM%, and in particular, the number of hard disks. The presence of 386 memory manager programs such as 386MAX and QEMM will invalidate the number returned in ExtRAM%. BSPINIT - Initialize printer Usage - Call BsPInit(Printer%, Rc%) Printer% The printer port number - 0 is LPT1, 1 is LPT2, etc. Rc% Return code - see BSPSTAT Programming notes: This service will initialize the printer. That is to say, it will: - Reset top-of-form - Return the printer to its default setup - poll the printer for printer status Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 36 BSPSTAT - Get printer status Usage - Call BsPStat(Printer%, Rc%) Printer% The printer port number - 0 is LPT1, 1 is LPT2, etc. Rc% Return code Programming notes: The return code is actually a series of bit settings that indicates the following conditions: - Printer ready - Acknowledge - Out of paper - I/O error (on some printers, this indicates an off-line condition) - Timeout - Selected When checking printer status, the 'selected' indicator tells you that the printer is on-line and ready to go. Some printers will return a "Printer ready' status even when turned off (this, incidentally, is why Quickbasic will occasionally print to a printer that is turned off and never return an error condition). Before issuing an LPRINT (or equivalent) command in Quickbasic, make sure that the printer is selected. The following code segment will extract the appropriate values. It is included in the sample program archive(Registered owners only). Printer% = 0 'Use LPT1 Call BsPStat(Printer%, Rc%) 'Get status of printer Printer.Ready% = (Rc% and 128) = 128 '1st bit indicates printer ready Acknowledge% = (Rc% and 64) = 64 '2nd bit indicates Ack Out.of.Paper% = (Rc% and 32) = 32 '3rd bit indicates out of paper IO.Error% = (Rc% and 8) = 8 '5th bit indicates I/O Error Timeout% = (Rc% and 1) = 1 '8th bit indicates Timeout Selected% = (Rc% and 16) = 16 '4th bit indicates Selected Locate 1,1: Color 15,1: Cls If Printer.Ready% then Print "Printer at LPT1 reports Ready" End if Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 37 If Acknowledge% then Print "Printer at LPT1 reports Acknowledge" End if If Out.of.Paper% then Print "Printer at LPT1 reports Out of Paper of Paper jam" End if If IO.Error% then Print "Printer at LPT1 reports I/O error or Printer off-line" End if If Timeout% then Print "Printer at LPT1 has timed out" End if If Selected% then Print "Printer at LPT1 is selected" End if BSPRINT - Print a string of characters Usage - Call BsPrint(Text$, Printer%, Rc%) Text$ String to print Printer% Printer port Rc% Return code Programming notes: See BSPSTAT for an explanation of return codes. This service sends whatever is in Text$ to the appropriate printer port. All special printer codes such as NewLine, TopofForm, etc, will be inter preted correctly by the printer. BSPRTSC - Print screen Usage - Call BsPrtSc Programming notes: This service is the equivalent of pressing the 'PrtSc' key on the key board. The screen will be printed to LPT1. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 38 The BIOS AT Disk Services Function Summary BSDAPARM - Get current drive parameters BSDATST - Test for drive ready BSDARST - Alternate disk reset BSDARCL - Recalibrate drive BSDADIAG - Perform controller diagnostics BSDASTAT - Detect diskette change BSDATYPE - Get disk type BSDASTYP - Set diskette type BSDASEEK - Position heads over a specified cylinder *********************** IMPORTANT ************************* These functions are documented only for AT type machines. These machines generally use a 1.2 Meg diskette drive whose characteristics are different enough from the 360KB drive to warrant these new BIOS services. These services also provide additional support for hard disks. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 39 BSDAPARM - Get current drive parameters Usage - Call BsDAParm(Drive$, Heads%, Cylinders%, Sectors%) Drive$ Letter designation of the target drive Heads% Maximum number of heads on the disk Cylinders% Maximum number of Cylinders/Head Sectors% Maximum number of Sectors/Cylinder Programming notes: This service will not function on a diskette drive. It is intended for use with a hard disk only. BSDATST - Test for drive ready Usage - Call DsDATst(Drive$, Rc%) Drive$ Letter designation of the target drive Rc% Return code Programming notes: This service will not function on a diskette drive. It is intended for use with a hard disk only. This service tests the status of the DRIVE READY signal on the selected drive. See BSDSTAT documentation for an explanation of return codes. BSDARST - Alternate disk reset Usage - Call BsDARst(Drive$, Rc%) Drive$ Letter designation of the target drive Rc% Return code Programming notes: Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 40 This service is the same as BSDRESET documented earlier except that BSDARST can be used only with hard disk controllers. See BSDSTAT documentation for an explanation of return codes. BSDARCL - Recalibrate drive Usage - Call BsDARcl(Drive$, Rc%) Drive$ Letter designation of the target drive Rc% Return code Programming notes: This service will not function on a diskette drive. It is intended for use with a hard disk only. This service instructs the specified drive to recalibrate. This is done by seeking track 0. This service should be used only after an error has been detected and before any retries are made. See BSDSTAT documentation for an explanation of return codes. BSDADIAG - Perform controller diagnostics Usage BsDADiag(Rc%) Rc% Return code Programming notes: This service will not function on a diskette drive. It is intended for use with a hard disk only. This service instructs the hard disk controller to perform its internal diagnostic routines. See BSDSTAT documentation for an explanation of return codes. BSDASTAT - Detect diskette change Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 41 Usage - Call BsDAStat(Drive$, Rc%) Drive$ Letter designation of the target drive Rc% Return code Programming notes: This service will detect whether or not the disk drive door has been opened since the last disk operation. It is meaningless for hard drives. This service should be used only with those drives that can detect disk changes (See BSDATYPE). See BSDSTAT documentation for an explanation of return codes. BSDATYPE - Get disk type Usage - Call BsDAType(Drive$, Rc%) Drive$ Letter designation of the target drive Rc% 0 - drive is not present 1 - diskette without change detection 2 - diskette with change detection% 3 - fixed disk Programming notes: This service will work with both hard and floppy disk drives. BSDASTYP - Set diskette type Usage - Call BsDASTyp(Drive$, Type%, Rc%) Drive$ Letter designation of the target drive Type% 1 - Double-density drive 2 - 360KB diskette in a 1.2MB drive 3 - 1.2MB diskette in a 1.2MB drive Rc% Return code Programming notes: Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 42 This service is meaningless for fixed disks. This service should be used prior to all Format and Verify requests to any 1.2MB diskette drives. See BSDSTAT for an explanation of return codes. BSDASEEK - Position heads over a specified cylinder Usage - Call BsDASeek(Drive$, Head%, Cylinder%, Rc%) Drive$ Letter designation of the target drive Head% Head to be positioned Cylinder% Cylinder over which the head will be positioned. Rc% Return code Programming notes: This service will not function on a diskette drive. It is intended for use with a hard disk only. This service can be used to park your fixed disk See BSDSTAT for an explanation of return codes. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 43 The File Attribute Services Function Summary FLGTIM - Get file creation time FLGDAT - Get file creation date FLGVOL - Get volume label FLPDAT - Change file creation date and time FLPVOL - Change volume label FLATTR - Change file attributes Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 44 FLGTIM - Get file creation time Usage - Call FlGTim(FlSpec$, FlTime$, Rc%) FlSpec$ Standard ASCIIZ file name FlTime$ File creation time in HH:MM:SS format Rc% Return code Programming notes: See function FLFIND for additional capabilities. An ASCIIZ string is the standard DOS filename followed by CHR$(0) FlTime$ must be initialized to 8 blanks prior to calling FLGTIM. If it is not properly initialized, a 'String Space Corrupt' error may occur. See Appendix D for valid return codes. Use FLFIND instead of FLGTIM whenever possible because it is tremendously faster. FLGDAT - Get file creation date Usage - Call FlGDat(FlSpec$, FlDate$, Rc%) FlSpec$ Standard ASCIIZ file name FlDate$ File creation date in MM-DD-YYYY format Rc% Return code Programming notes: See function FLFIND for additional capabilities. An ASCIIZ string is the standard DOS filename followed by CHR$(0) FlDate$ must be initialized to 10 blanks prior to calling FLGDAT. If it is not properly initialized, a 'String Space Corrupt' error may occur. See Appendix D for valid return codes. Use FLFIND instead of FLGDAT whenever possible because it is tremendously Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 45 faster. FLGVOL - Get volume label Usage - Call FlGVol(Drive$, Vol$) Drive$ Letter designation of drive Vol$ Volume label of the target drive Programming notes: Vol$ must be initialized to 11 blanks prior to calling FLGVOL. If it is not properly initialized, the entire volume label may not be returned in this field. No return code is provided for this function. If an invalid Drive letter is passed or if the target drive does not have a volume label, the con tents of Vol$ will remain unchanged. If Drive$ is initialized to nulls (i.e. Drive$ = ""). The volume label of the default drive is returned. This function will not work properly with diskettes fromatted under DOC V4.00 or higher. FLPDAT - Change file creation date and time Usage - Call FlPDat(Flspec$, FlDate$, FlTime$, Rc%) FlSpec$ Standard ASCIIZ file name FlDate$ File creation date in MM-DD-YYYY format FlTime$ File creation time in HH:MM:SS format Rc% Return code Programming notes: See function FLFIND for additional capabilities. An ASCIIZ string is the standard DOS filename followed by CHR$(0) FlDate$ must be initialized to a valid 10 character date prior to calling Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 46 FLPDAT. If an invalid date is used or a date that is not 10 characters is used, FLPDAT will place garbage in the file creation date. This is not harmful to the date contained in the file, but may interfere with some MAKE or Backup processes. FlTime$ must be initialized to a valid 8 character time prior to calling FLPDAT. See discussion of FlDate$ for implications of using invalid times. See Appendix D for valid return codes. FLPVOL - Change volume label Usage - Call FlPVol(Drive$, Vol$, Rc%) Drive$ Letter designation of drive Vol$ Volume label to be written to target drive Rc% Return code Programming notes: Vol$ must be initialized to an 11 character string before calling FLPVOL. If it is not properly initialized, an incorrect volume label may be writ ten to the disk. See Appendix D for return codes. If Drive$ is initialized to nulls (i.e. Drive$ = ""). The volume label of the default drive is updated. This function will not work properly under DOS V4.00. FLATTR - Change file attributes Usage Call FlAttr(FlSpec$, Mode%, Attr%, Rc%) FlSpec$ Standard ASCIIZ file name Mode% 0 - Get attributes 1 - Set attributes Attr% New file attributes (if Mode% = 1) or current file attributes (if Mode% = 0). Rc% Return code Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 47 Programming notes: See function FLFIND for additional capabilities. An ASCIIZ string is the standard DOS filename followed by CHR$(0) Attr% is an integer between 0 and 63. Attributes are bit settings within this number and they are represented as: Normal 0 Readonly 1 Hidden 2 System 4 Volume 8 Subdir 16 Archive 32 The following code segment will interpret the Attr% field. FlSpec$ = "command.com"+chr$(0) 'Target filename Mode% = 0 'Indicate get attributes Call FlAttr(FlSpec$, Mode%, Attr%, Rc%) If Rc% <> 0 then goto Error.Routine 'Non-zero indicates failure If Attr% = 0 then Normal% = -1 'zero indicates no special Goto Print.Attr 'attributes End if FRead% = (Attr% and 1) = 1 'Check for readonly attr FHidden% = (Attr% and 2) = 2 'Check for hidden attr FSystem% = (Attr% and 4) = 4 'Check for system attr FVolume% = (Attr% and 8) = 8 'Check for Volume label FSubdir% = (Attr% and 16) = 16 'Check if its a sub-directory FArcive% = (Attr% and 32) = 32 'Check if its been archived Print.Attr: Attributes$ = "" If Normal% then Attribute$ = "Normal " If FRead% then Attribute$ = "Read Only " If Fhidden% then Attribute$ = Attribute$ + "Hidden " If Fsystem% then Attribute$ = Attribute$ + "System " If FSubdir% then Attribute$ = Attribute$ + "Directory " If FArcive% then Attribute$ = Attribute$ + "Archive" Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 48 Print "FlSpec$", Attribute$ A program segment in the Sample programs (Registered copies only) shows how to initialize Attr% to set attributes. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 49 The File Access Services Function Summary FLSET - Set number of file handles FLOPEN - Open a file FLCLOS - Close a file FLREAD - Read a record from a file FLWRIT - Write a record to a file FLPOINT - Point to a specific record in a file FLCREAT - Create a file FLDELETE - Delete a file FLRSECT - Read a sector FLWSECT - Write a sector Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 50 FLSET - Set number of available file handles Usage - Call FlSet(Handles%, Rc%) Handles% Maximum number of allowable files Rc% Return code Programming notes: See Appendix D for an Explanation of return codes. This function can be used to allow more than 15 open files at one time. Under normal circumstances, Quickbasic will allow you to open the number of files specified in your CONFIG.SYS. QB will allocate 5 files at startup time. If you specify FILES=10 in your CONFIG.SYS, QB uses 5 and allows you to use the remaining 5 files - up to a maximum of 15. This function allows you to increase the number of files you can open to about 60. The actual DOS limit is 255, but each file requires space in your programs data segment, so the practical limit becomes about 60. This will vary depending upon your programs use of the near heap (strings, etc.). This function will never allow you to open more files than the number specified in the FILES line of your CONFIG.SYS. If you want to open 40 files, you must do the following: - place FILES=45 in config.sys (minimum) - Call FlSet(45) (5 files for QB, 40 for your program This function is available only in DOS V3.30 or higher. FLOPEN - Open a file Usage - Call FlOpen(FlSpec$, Mode%, Share%, Handle%, Rc%) FlSpec$ Valid ASCIIZ file name Mode% Specifies the use mode - valid values are: 0 - Read only access 1 - Write only access 2 - Read/Write access Share% Specifies the file sharing mode in multi-tasking envi ronments. Valid values are: 1 - exclusive use 2 - allow read access only 3 - allow write access only 4 - allow read/write access(full sharing) Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 51 Handle% Token returned by DOS to identify the opened file. Rc% Return code Programming notes: See Appendix D for an explanation of return codes. Share% is valid only for DOS 3.XX. DOS 2.XX users should always have Share% = 0. This service will open a file with normal, system, or hidden attribute. Handle% is an integer that DOS uses to identify the file. Most of the other services in this section of the manual require that Handle% be passed to then. After an open is successfully completed, the current record pointer is set at the start of the file. FLCLOS - Close a file Usage - Call FlClos(Handle%, Rc%) Handle% Handle of the file being closed. Rc% Return code Programming notes: See Appendix D for an explanation of return codes. Handle% is the token returned by FLOPEN. Any file opened with FLOPEN must be closed with FLCLOS. Initializing Handle% improperly may have some unpredictable results, such as locking the keyboard or disabling the printer and/or monitor. FLREAD - Read a record from a file Usage - Call FlRead(Handle%, Databuf$, Buflen%, Rc%) Handle% Handle of the file being read. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 52 Databuf$ Data area where the record will be placed after success ful completion of the read. Buflen% Number of bytes to read. FLREAD will return the actual number of bytes read. Rc% Return code Programming notes: See Appendix D for an explanation of return codes. FLREAD returns the record being pointed to by the current record pointer. After a successful read, FLREAD will update the current record to point to the next record in the file. Initialize Buflen% to the number of bytes that you would like to read. FLREAD will update this field with the actual number of bytes read. When Buflen% is zero, or when it is less than it's initial value, end-of-file has been reached. It is the programmer's responsibility to insure that Databuf% is long enough to accommodate the record read from disk. If it is not initialized properly, a 'String Space Corrupt' error will probably occur. The follow ing section of code shows a method of initializing Databuf$. Buflen% = 512 'Number of bytes to read Databuf$ = Space$(Buflen%) 'Create an adequate buffer FLWRIT - Write a record to a file Usage - Call FlWrit(Handle%, Databuf$, Buflen%, Rc%) Handle% Handle of the file being written to. Databuf$ Data area containing the record to be written. Buflen% Number of bytes to write. Rc% Return code Programming notes: See Appendix D for an explanation of return codes. FLWRIT writes the record at the position pointed to by the current record Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 53 pointer. After a successful write, FLWRIT will update the current record to point the next record in the file. Initialize Buflen% to the number of bytes that you would like to write. FLWRIT will update this field with the actual number of bytes written. When Buflen% is zero, or when it is less than it's initial value, a disk full condition has been reached. FLPOINT - Point to a specific record in a file Usage - Call FlPoint(Handle%, Recno%, Reclen%, Rc%) Handle% Handle of the file being operated on. Recno% Record number that you would like to point to (relative to the beginning of the file). Reclen% Length of a logical record. Rc% Return code Programming notes: See Appendix D for an explanation of return codes. DOS will use Recno% and Reclen% to compute the offset of the record within the file. This service updates the current record pointer. Specifying Recno% = 0 will position you at the beginning of the file. Specifying Recno% = -1 will position you at the end of the file (Useful for adding records to the end of a file). DOS does not perform boundary checks on this function, so specifying Recno% or Reclen% improperly may set the current record pointer outside the limits of the file. FLCREAT - Create a file Usage Call FlCreat(FlSpec$, Mode%, Attr%,, Handle%, Rc%) FlSpec$ Valid ASCIIZ filename (except for Mode% = 2) Mode% Indicates open actions: 0 = Create the file if it doesn't exist - if it does Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 54 exist, truncate the file. 1 = Create the file if it doesn't exist - if it does exist this service will fail 2 = Create a temporary file with a unique file name Handle% Handle assigned by DOS to the file Attr% File attributes assigned to this file. Rc% Return code Programming notes: See Appendix D for an explanation of return codes. See the documentation on FLATTR for an explanation of what to put in Attr% When Mode% is 2 Dos will create a temporary file and the name of the file will be returned in FlSpec$. These files are not automatically deleted when the program terminates. That is the responsibility of the program mer. When a file is created, it is automatically opened for read/write access. No subsequent open is required to access the file, but you must close the file before the program terminates. When Mode% is 2 FlSpec$ must be initialized properly prior to calling FLCREAT. It should consist of an ASCIIZ path name followed by 12 blanks. For example: FlSpec$ = Chr$(0) + Space$(12) 'Current directory FlSpec$ = "C:\" + Chr$(0) + Space$(12) 'Root directory FlSpec$ = "\TEMP" + Chr$(0) +Space$(12) '\TEMP directory FLDELETE - Delete a file Usage FlDelete(FlSpec$, Rc%) Flspec$ Valid ASCIIZ filename Rc% Return code Programming notes: See Appendix D for an explanation of return codes. FlSpec$ may not use wildcard characters. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 55 This service should be used to delete files created using Mode% = 2 with FLCREAT (close it first before deleting it). FLRSECT - Read a sector Usage - Call FlRSect(Numsect%, Databuf$, Sector%, Rc%) Numsect% Number of sectors to read Databuf$ Data area where the data will be placed after successful completion of the read. Sector% Sector where read operation will start Rc% Return code Programming notes: Databuf$ must be long enough to hold the data read by this service. If it is not, you will probably get a 'String Space Corrupt' error. Sectors are generally 512 bytes. You can find out by using FLDSTAT - explained later in the manual. Sector% is the relative sector from the beginning of the disk, starting with sector 0. A return code of 0 indicates successful completion. There are a large number of return codes that can indicate failure. These will not be docu mented here - if you really need them, write and we will gladly send them to you. If you are reading more than one sector, the sectors will be retrieved sequentially starting at Sector%. e.g. if Sector% = 5 and Numsect% = 3, then this service will read sectors 5,6,an 7. FLWSECT - Write a sector Usage - Call FlWSect(Numsect%, Databuf$, Sector%, Rc%) Numsect% Number of sectors to written Databuf$ Data area containing the data to be written. Sector% Sector where write operation will start Rc% Return code Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 56 Programming notes: Sector% is the relative sector from the beginning of the disk, starting with sector 0. A return code of 0 indicates successful completion. There are a large number of return codes that can indicate failure. These will not be docu mented here - if you really need them, write and we will gladly send them to you. If you are writing more than one sector, the sectors will be written sequentially starting at Sector%. e.g. if Sector% = 5 and Numsect% = 3, then this service will write sectors 5,6,an 7. ************************** IMPORTANT *********************************** Indiscriminate use of this function can cause serious problems with your disk. Accidentally writing over the boot sector or the FAT can destroy all of the data on your disk. TAKE A BACKUP before testing this service, especially if you are writing to a HARD DISK. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 57 DOS Replacement Services Function Summary FLFIND - Find a file or group of files FLCNT - Count the number of matching files FLMOVE - Move a file FLCOPY - Copy a file to another file FLSDRV - Set the current drive FLGDRV - Get the current drive FLCDIR - Change the current directory FLGDIR - Get the current directory FLMDIR - Make a directory FLDDIR - Delete a directory FLDSTAT - Retrieve disk statistics Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 58 FLFIND - Find a file or group of files Usage - Call FlFind(FlSpec$, VARPTR(Dirlist$(0))) FlSpec$ Standard ASCIIZ filename Dirlist$(0) Array containing all files matched by FlSpec$ Programming notes: FLFIND will return a list of all files in the current directory that match FlSpec$. Wildcards can be used. Each entry in Dirlist$ must be initialized to 40 blanks. If each element is not properly initialized, a 'String Space Corrupt' error may occur. Dirlist$ must be properly dimensioned so that all files matching FlSpec$ can fit into the array. If it is not properly dimensioned, unpredictable results can occur (probably 'String Space Corrupt', but anything can hap pen). Use FLCNT to properly dimension the array. FLFIND can be used to determine the presence or absence of a file. See LOOK.BAS in the sample programs for an example of using FLCNT and FLFIND. This program will search an entire disk looking for matches (Wildcards are okay to use with LOOK.BAS). FLCNT - Count the number of matching files Usage - Call(FlCnt(FlSpec$, Count%) FlSpec$ Standard ASCIIZ filename Count% Number of files matching FlSpec$ Programming notes: FLCNT will return a count of all files in the current directory that match FlSpec$. Wildcards can be used. FLCNT can be used to determine the presence or absence of file. FLCNT should be used prior to calling FLFIND to ensure that the passed array is large enough. See LOOK.BAS in the sample programs (registered users only) for an example Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 59 of using FLCNT and FLFIND. This program will search an entire disk look ing for matches (Wildcards are okay to use with LOOK.BAS). FLMOVE - Move a file Usage - Call FlMove(Old.FlSpec$, New.FlSpec$, Rc%) Old.FlSpec$ Standard ASCIIZ filename New.FlSpec$ Standard ASCIIZ filename Rc% Return code Programming notes: New.FlSpec$ can be any valid DOS filename that is not currently in use. You may specify a different directory, but you cannot move a file to a different device. Wildcards are not allowed. (A DOS wildcard is an '*' or a '?') See Appendix D for an explanation of return codes. FLCOPY - Copy a file to another file Usage - Call FlCopy(Old.Flspec$, New.Flspec$, Rc%) Old.FlSpec$ Standard ASCIIZ filename New.FlSpec$ Standard ASCIIZ filename Rc% Return code Programming notes: New.FlSpec$ must be a valid DOS filename. If it already exists, it will be overwritten. This function is somewhat slower than the DOS copy command. If a faster copy is needed, modify the Assembly source code to provide a larger buf fer (registered users only). See Appendix D for an explanation of return codes. FLSDRV - Set the current drive Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 60 Usage - Call FlSDrv(Drive$) Drive$ Drive letter designation Programming notes: This service does not return a completion code. It is up to the program mer to insure that Drive$ is a valid drive designation (See FlGDrv to determine the number of drives). FLGDRV - Get the current drive Usage - Call FlGDrv(Drive$, Max.Drive$) Drive$ Drive letter designation Max.Drive$ Letter of the highest drive designation that Dos will recognize. Programming notes: Drive$ must be initialized to a single blank. If it is not properly ini tialized, this service will not function and a 'String Space Corrupt' error may occur. Max.Drive$ is the highest letter designation that DOS will recognize. DOS assigns drive designators sequentially, so generally, if Max.Drive$ = 'D', that should mean that drives A,B, and C are valid. On some machines, Max.Drive$ may not be a valid drive. It may be the drive specified by the LASTDRIVE parameter of your CONFIG.SYS file. For consistent accurate results with this function, properly set LASTDRIVE in your CONFIG.SYS file. FLCDIR - Change the current directory Usage - Call FlCDir(Dir$, Rc%) Dir$ Valid directory name (ASCIIZ string) Rc% Return code Programming notes: Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 61 See Appendix D for an explanation of return codes. Dir$ must be a valid directory name preceded by a '\' and followed by a Chr$(0) FLGDIR - Get the current directory Usage - Call FlGDir(Dir$) Dir$ Valid directory name (ASCIIZ string) Programming notes: Dir$ must be initialized to 64 blanks prior to calling FLGDIR. If it is not initialized properly, a 'String Space Corrupt' may result. The current directory is returned in Dir$. It is not preceded by a '\'. FLMDIR - Make a directory Usage - Call FlMDir(Dir$, Rc%) Dir$ Valid directory name (ASCIIZ string) Rc% Return code Programming notes: See Appendix D for an explanation of return codes. Dir$ must be a valid directory name preceded by a '\' and followed by a Chr$(0) FLDDIR - Delete a directory Usage - Call FlDDir(Dir$, Rc%) Dir$ Valid directory name (ASCIIZ string) Rc% Return code Programming notes: See Appendix D for an explanation of return codes. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 62 Dir$ must be a valid directory name preceded by a '\' and followed by a Chr$(0) FLDSTAT - Retrieve disk statistics Usage - Call FlDStat(Drive$, Type%, Bytes.Sector%, Sector.Cluster%, _ Avail.Cluster%, Total.Cluster%, Rc%) Drive$ Valid letter drive designation Type% Type of drive Bytes.Sector% Number of bytes in a sector on the target disk Sector.Cluster% Number of sectors in a cluster on the target disk Avail.Cluster% Number of unused clusters on the target drive Total.Cluster% Number of clusters on the target drive Rc% Return code Programming notes: See Appendix D for an explanation of return codes. Type% will indicate the type of drive. Possible values are: 255 - DSDD 8 Sectors/Track 254 - SSDD 8 Sectors/Track 253 - DSDD 9 Sectors/Track 252 - SSDD 8 Sectors/Track 249 - HD 15 Sectors/Track 248 - Fixed disk Most RAM drives will appear to be a fixed disk. Available space on the disk can be computed by the formula: Bytes.Sector% * Sector.Cluster% * Avail.Cluster% Total space on the disk can be computed by the formula: Bytes.Sector% * Sector.Cluster% * Total.Cluster% Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 63 Miscellaneous DOS Services Function Summary BOOT - Initiate a cold or warm boot DOSEXIT - Terminate with a return code DOSEXEC - SHELL replacement DOSCHOUT - Write a string to the standard output device DOSCHRIN - Read a character from the standard input device DOSSTRIN - Read a string from the standard input device DOSRED - Redirect a DOS standard handle DOSPRSC - Print the screen DOSVER - Get the DOS version DOSVRFY - Turn verify mode on and off Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 64 BOOT - Initiate a cold or warm boot Usage - Call Boot(Function%) Function% 0 - Perform a warm boot 1 - perform a cold boot Programming notes: There is no return from this function - it restarts the machine. A warm boot is the equivalent of pressing Alt-Ctrl-Del - a cold boot is the equivalent of turning the machine off and then on again. DOSEXIT - Terminate with a return code Usage - Call DosExit(Rc%) Programming notes: This function can be used to terminate a program with a return code. The return code can then be used in an ERRORLEVEL statement in a batch file. The return code must be in the range 0-255. DO NOT USE THIS FUNCTION WITHIN THE QUICKBASIC DEVELOPMENT ENVIRONMENT. IT WILL TERMINATE QUICKBASIC. DOSEXEC - SHELL replacement Usage - Call DosExec(ProgName$, EnvBlock$, CmdTail$, Rc%, PRc%, TermTyp%) ProgName$ The fully qualified name of the program or batch file to execute. (i.e. - ProgName$ = "c:\dos\edlin.exe") EnvBlock$ Environment block to be used by the sub-process. CmdTail$ COMMAND line argument Rc% Function return code 0 - Successful 1 - Invalid function 2 - Insufficient memory 5 - Access denied 10 - Invalid environment 11 - Invalid format PRc% Program return code (0-255) Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 65 TermTyp% Termination method 0 - Normal termination 1 - Terminated with Ctrl-C 2 - Terminated with Critical error 3 - Loaded as TSR Programming notes: Set EnvBlock$ = "" to use the default environment. If you set up your own environment, be sure to include the COMSPEC variable. Each line in the environment must terminate with CHR$(0). See the sample program included in the registered version. If TermTyp% equals 3 upon return, the sub-process has loaded itself as a TSR and Quickbasic probably will not run. DOSCHOUT - Write a string to the standard output device Usage - Call DosChOut(Str.Out$) Str.Out$ Text to be written Programming notes: If the standard output device is CON (monitor), the text is written to the current cursor location. Printing control characters(i.e. carriage return, line feeds) will cause the cursor to move accordingly. All data is written in 'raw' mode - this bypasses certain checking that DOS normally would do and increases output speed a little. Do not print chr$(255) as this will cause a keyboard read to occur. This service, like the other DOS keyboard/con services, can be re-directed. DOSCHRIN - Read a character from the standard input device Usage - Call DosChrIn(Char.In$, Echo%, Rc%) Char.In$ Character returned from the standard input device. Echo% 0 - do not echo to standard output 1 - echo to standard output Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 66 Rc% 0 - indicates no character was found 1 - indicates character returned in Char.In$ 2 - indicates an extended ASCII character was returned in Char.In$ Programming notes: Extended ASCII characters will not echo. No special action is taken if Ctrl-C or Ctrl-Break is detected. Char.In$ must be initialized to a space. If it is not, the service will fail and a "String Space Corrupt' condition may occur. If an extended ASCII code is entered, Char.In$ will contain the second character of the code. This service, like the other DOS keyboard/con services, can be re-directed. DOSSTRIN - Read a string from the standard input device Usage - Call DosStrIn(Text.In$, Count%) Text.In$ input string Count% length of input string Programming notes: Use this function only for input of a single string on a screen. The editing characteristics of this service do not lend themselves to full screen input. No extended ASCII codes are allowed by this function. The maximum input length is the length of Text.In$ - 3. For example, if you wanted input with a maximum length of 12 characters, use the following code: Text.In$ = Space$(15) 'Maximum length + 3 call DosStrIn(Text.In$, Count%) End of input is signaled by pressing the [Enter] key. If you type in more than the maximum number of characters, the beep will sound until [Enter] is pressed. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 67 No cursor will be displayed while characters are being entered. The characters entered at the keyboard will echo on the monitor at the current cursor position. This service, like the other DOS keyboard/con services, can be re-directed. DOSRED - Redirect a DOS standard handle Usage - Call DosRed(Device%, FileSpec$, Rc%) Device% Device to redirect 0 - Standard input 1 - Standard output 3 - Standard AUX device 4 - Standard list device Filespec$ Standard ASCIIZ string Rc% Return code Programming notes: See the Appendix D for an explanation of return codes. The standard input device is CON, or the keyboard. If you redirect this device to accept from a file, you cannot detect end-of-file. If you play with this device, be prepared to reboot quite a bit while testing - incor rect handling can easily cause the keyboard to lock up. The standard output device is CON, or the monitor. You can redirect this device either to a file or printer. Once redirected, all PRINT statements will print to FileSpec$. See the sample program TYPER.BAS included with this package. The standard auxiliary device is AUX - generally COM1. The standard list device is PRN - generally LPT1. Unfortunately, Basic does not use the standard list device for LPRINT statements or for PRINT# statements, thereby making redirection of this handle a little less useful than it could be. If FileSpec$ is NUL (i.e. FileSpec$ = ""), DOSRED will reset the device to its default value. these are: Device% Default 0 CON Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 68 1 CON 3 AUX 4 PRN If FIleSpec$ is CHR$(255), DOSRED will simply close that handle. This is useful if you're not using DOS 3.3 and you need more than fifteen files open at one time (the Quickbasic limit). Simply close one of the devices, and that allows you to open another file. If you close the standard input device, be sure to reopen it as you won't be able to get any input from the keyboard. Rumor has it that under DOS 3.3, you can have up to 255 files open at any one time. If FileSpec$ is a disk file, and it already exists, DOSRED will simply write over it. If it does not exist, DOSRED will create it. You must close any disk files used for redirection before terminating your program. Otherwise, the file's directory entry (length) will not be updated and you will not be able to process that file. A file close is done automatically when you issue a reset (FileSpec$ = ""). DOSPRSC - Print the screen Call DosPrSc Programming notes: This service will print the contents of the screen buffer. It is really a BIOS service, but because of it's usefulness, it is included here. DOSVER - Get the DOS version Usage - Call DosVer(Version%) Version% the version of DOS currently running Programming notes: Version is returned as an integer. DOS 3.10 would be returned as 310, and so on. To display it properly, use the following code: Call DosVer(Version%) Print Using "#.##";Version%/100 DOSVRFY - Turn verify mode on and off Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 69 Usage - Call DosVrfy(Function%) Function% 0 - turn verify off 1 - turn verify on -1 - get status of verify Programming notes: When verify is on, every write request made through DOS will cause DOS to reread the sector just written to insure that it is readable. No verification is done when BIOS is used to write a sector. DOS does NOT perform a verify by checking that the sector written matches the data in the output buffer. It simply insures that the sector written can be read and that it passes the CRC. Verify does add overhead when it is turned on. Use this service when the output media is questionable. When using Function% = -1, DOSVRFY will return a 0 in Function% if Verify is off and a 1 if Verify is on. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 70 The Print Spooler YOU MUST HAVE VERSION 3.XX OF DOS TO USE THESE SERVICES Function Summary DOSPSTAT - Request spooler status DOSPCAN - Cancel all spooled files DOSPDEL - Delete a file from the queue DOSPLST - List all files in the queue DOSPSUB - Submit a file to the queue Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 71 DOSPSTAT - Request spooler status Usage - Call DosPStat(Rc%) Rc% 0 - Normal status - okay to use spooler 1 - Spooler is inactive 2 - Spooler unavailable 255 - Invalid request (invalid DOS version) Programming notes: This service simply provides the spooler status. Each service in this section also checks the spooler status. The only good return code is 0. Any of the other return codes indicate that the spooler is not useable. A return code of 1 indicates the spooler is not running, but it could be started from the DOS prompt. A return code of 2 indicates that the spooler is not active and it cannot be started because some other process has captured the spooler interrupt. A return code of 255 indicates that the wrong version of DOS is installed - version 3.00 or higher is needed. See Appendix E for a discussion on starting the print spooler. DOSPCAN - Cancel all spooled files Usage - Call DosPCan(Rc%) Rc% Return code Programming notes: See Appendix E for an explanation of return codes. This service will delete all files from the print queue. Please remember that most printers have a print buffer - some as large as 256k. This function will not clear the print buffer. DOSPDEL - Delete a file from the queue Usage - Call DosPDel(FileSpec$, Rc%) Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 72 Filespec$ ASCIIZ string Rc% Return code Programming notes: Filespec$ should be the name of a file in the print queue in ASCIIZ for mat. ASCIIZ format is simply the file name followed by a CHR$(0), for example: Filespec$ = "C:\SPOOLDIR\TEXTFILE.DAT" +CHR$(0) You must use the entire filename (including drive and path) when deleting a file from the queue. See Appendix E for an explanation of return codes. This service will delete a files from the print queue. Please remember that most printers have a print buffer - some as large as 256k. This function will not clear the print buffer, so if the deleted file is print ing, it will continue to print until the buffer is emptied. DOSPLST - List all files in the queue Usage - Call DosPLst(File.Array$(0), Rc%) File.Array$ Array that will contain the names of all the files in the print queue Rc% Return code Programming notes: See Appendix E for a explanation of return codes. File.Array$ must be initialized and have the proper number of elements prior to calling DOSPLST. Failing to initialize it properly will cause DOSPLST to fail and probably freeze up your computer. The maximum number of entries depends on what parameters were used when the print spooler was started. The absolute maximum is 32. I would strongly recommend that you plan for the maximum. The following code seg ment shows the proper method of using DOSPLST. MaxQueue% = 31 'This is really 32 entries when 'using Option Base 0 Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 73 Dim File.Array$(MaxQueue%) 'plan for max number of entries For X% = 0 to MaxQueue% 'initialize the array File.Array$ = Space$(64) 'max length of a filename Next Call DosPLst(File.Array$(0), Rc%) 'go get list If Rc% <> 0 then goto YOUR.ERROR.ROUTINE DOSPSUB - Submit a file to the queue Usage - Call DosPSub(FileSpec$, Rc%) FileSpec$ ASCIIZ string Rc% Return code Programming notes: FileSpec$ is the name of the file to be submitted to the print queue. See Appendix E for an explanation of return codes. The file is placed at the tail of the print queue. It will not print until all other files ahead of it have already printed. There is no way of prioritizing the files with the services presented here. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 74 String Functions Function Summary VERIFY - Verify all characters in a string XVERIFY - Slightly different twist on VERIFY CHARXLAT - Replace multiple characters in a string TRANSLAT - Replace all occurrences of a character in a string COMPRESS - Remove leading and trailing blanks UPCASE - Convert all characters in a string to upper case LOCASE - Convert all characters in a string to lower case PROPER - Convert a string to a proper name HEXSTR - Convert a string to its hexadecimal equivalent Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 75 VERIFY - Verify all characters in a string Usage Call Verify(Target$, Mask$, Rc%) Target$ String to be verified Mask$ String of characters to be verified in Target$ Rc% Return code - 0 if all characters in Target$ are contained in Mask$, otherwise, the position of the first character in Target$ that is not contained in Mask$ Programming notes: Identical to the PL/I Verify function. It is useful for validating a field for all character or all numeric. For example: Find the first non-blank character in Target$ Call Verify (Target$, Space$(1), Rc%) NonBlank$ = Mid$(Target$, Rc%,1) Determine if Target$ is all numeric Call Verify (Target$, "0123456789", Rc%) If Rc% = 0 then GoTo Target.Numeric Else GoTo Target.NonNumeric End if XVERIFY - Slightly different twist on VERIFY Usage Call XVerify(Target$, Mask$, Rc%) Target$ String to be verified Mask$ String of characters to be verified in Target$ Rc% Return code - 0 if all characters in Target$ are contained in Mask$, otherwise, the position of the last character in Target$ that is not contained in Mask$ Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 76 Programming notes: Identical to the PL/I Verify function. It is useful for validating a field for all character or all numeric. For example: Find the first non-blank character in Target$ Call XVerify (Target$, Space$(1), Rc%) NonBlank$ = Mid$(Target$, Rc%,1) Determine if Target$ is all numeric Call XVerify (Target$, "0123456789", Rc%) If Rc% = 0 then GoTo Target.Numeric Else GoTo Target.NonNumeric End if ***** REMEMBER, VERIFY RETURNS THE POSITION OF THE FIRST CHARACTER ***** ***** IN TARGET$ THAT IS NOT FOUND IN MASK$ - XVERIFY RETURNS THE ***** ***** POSITION OF THE LAST CHARACTER. CHARXLAT - Replace multiple characters in a string Usage Call CharXlat(Str1$, TrTable$) Str1$ String to be translated TrTable$ 256 Byte translate table Programming notes: This function will take each character in Str1$ and change it to a corresponding value specified in TrTable$. For example, the character '1' has an ASCII value of 31. This function will replace every occurrence of the character '1' in Str1$ with whatever is in the 31st byte of TrTable$. For example, the following code segment (taken from DUMP.BAS in the sample program archive) will change all non-displayable characters in a string into a .(period). Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 77 TrTable$ = String$(256,".") For x% = 31 to 126 MID$(TrTable$, x% + 1, 1) = CHR$(x%) NEXT Call CharXlat(Str1$, TrTable$) Str1$ can now be safely be displayed on a screen. TRANSLAT - Replace all occurrences of a character in a string Usage Call Translat(Str1$, Target$, Repl$) Str1$ String to be translated Target$ Character to be replaced Repl$ Replacement character Programming notes: This function will replace each occurrence of Target$ in Str1$ and replace it with Repl$. For example: Str1$ = "aabbcc" Target$ = "b" Repl$ = "x" Call Translat(Str1$, Target$, Repl$) Print Str1$ would display the string "aaxxcc". COMPRESS - Remove leading and trailing blanks Usage - Rem $Include: 'compress.fn' Str1$ = FnCompress$(Str2$) Str1$ Any string Str2$ Str1$ with leading and trailing blanks removed Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 78 Programming notes: QB V4.0 also provides a similar function. This one is a little faster. UPCASE - Convert all characters in a string to upper case Usage - Call UpCase(Str1$) Str1$ any string Programming notes: This function became available with QB V4.0. UPCASE is a little faster. LOCASE - Convert all characters in a string to lower case Usage - Call LoCase(Str1$) Str1$ any string Programming notes: This function became available with QB V4.0. LOCASE is a little faster. PROPER - Convert a string to a proper name Usage - Call Proper(Str1$) Str1$ any string Programming notes: Proper works by making the first letter of each word upper case and making all subsequent letters lower case. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 79 HEXSTR - Convert a string to its hexadecimal equivalent Usage - Call HexStr(Str1$, Str2$) Str1$ any string Str2$ A string initialized to spaces. Its' length must be at least twice that of Str1$. Programming notes: This function returns the hexadecimal equivalent of Str1$ in Str2$. For example: Str1$ = "123" Str2$ = Space$(2*LEN(Str1$)) Call HexStr(Str1$, Str2$) Print Str2$ would display '313233' on your screen. See DUMP.BAS in the sample program archive for an example. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 80 Date/Time Functions Function Summary DATEPACK - Pack a date into two bytes DATEUNPK - Unpack a date packed with DATEPACK GREGTJUL - Convert a date from Gregorian to Julian format JULTGREG - Convert a date from Julian to Gregorian format DAYSDIFF - Compute the number of days between two dates WEEKDAY - Determine the day of the week CALENDAR - Pop-up a calendar anywhere on the screen ADDTIME - Add two times together SUBTIME - Subtract two times TIME - Timer services TICKS BSGETIME Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 81 DATEPACK - Pack a date into two bytes Usage Call DatePack(UnpkDate$, PackDate$) UnpkDate$ Date in MM/DD/YYYY format PackDate$ Two byte packed date returned by the routine Programming notes: A '9' in the first byte of PackDate$ indicates an error has occurred. PackDate$ must be initialized to 2 spaces before calling the routine. For example: UnpkDate$ = "01/01/1988" PackDate$ = Space$(2) Call DatePack$(UnpkDate$, PackDate$) DATEUNPK - Unpack a date packed with DATEPACK Usage Call DateUnpk(UnpkDate$, PackDate$) UnpkDate$ Date in MM/DD/YYYY format returned by routine PackDate$ Two byte packed date created by PACKDATE Programming notes: A '9' in the first character of PackDate$ indicates an error has occurred. UnpkDate$ must be initialized to 10 spaces before calling the routine. For example: UnpkDate$ = "01/01/1988" PackDate$ = Space$(2) Call DatePack$(UnpkDate$, PackDate$) . . . UnpkDate$ = Space$(10) Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 82 Call DateUnpk$(UnpkDate$, Packdate$) GREGTJUL - Convert a date from Gregorian to Julian format Usage Call GregTJul(GregDate$, JulDate$) GregDate$ Date in MM/DD/YY format JulDate$ Date in YYDDD format returned by the routine Programming notes: GregTJul is written in QuickBasic. GregTJul does not validate GregDate$, so a date like "00/30/1988" will cause an Illegal function call. JULTGREG - Convert a date from Julian to Gregorian format Usage Call JulTGreg(GregDate$, JulDate$) GregDate$ Date in MM/DD/YY format returned by the routine JulDate$ Date in YYDDD format Programming notes: JulTGreg is written in QuickBasic. JulTGreg does not validate JulDate$, so a date like "88999" will cause an Illegal function call. DAYSDIFF - Compute the number of days between two dates Usage Call DaysDiff(Date1, Date2$, Diff%) Date1$ Date in MM/DD/YY format Date2$ Date in MM/DD/YY format Diff% Number of days between Date1$ and Date2$ Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 83 Programming notes: DaysDiff is written in QuickBasic and uses GregTJul. DaysDiff does not validate dates, so a date like "31/31/88" will cause an Illegal function call. This routine returns the number of days between Date1$ and Date2$. For Example: Date1$ = "01/01/88" Date2$ = "01/02/88" Call DaysDiff(Date1$, Date2$, Diff%) A '1' would be returned in Diff%. If Date1$ is less than Date2$, Diff% will be positive. If Date1$ is equal to Date2$ then Diff% will be zero, otherwise Diff% will be negative. As it stands, DaysDiff cannot handle dates that are more than 32000 days apart. If you need to handle this, change Diff% from integer to single precision (Change the Call statement, and any reference to Diff in the subroutine itself). WEEKDAY - Determine the day of the week Usage - Call WeekDay(Date1$, Day%) Date1$ Date in MM/DD/YY format Day% Day of the week - 0 = Sunday Programming notes: This routine uses DOS services to determine day of week, so it works only for dates between 1980 and 1999. A value of -1 in Day% indicates an error has occurred. CALENDAR - Pop-up a calendar anywhere on the screen Usage - Call Calendar(Top.Row%, Left.Col%, FgColor%, BgColor%) Top.Row% Top row of the calendar Left.Col% Left Column Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 84 FgColor% Foreground color BgColor% Background Color Programming Notes: This month's calendar is placed on the screen in the coordinates indi cated. The [Arrow] keys will change the month and year being displayed. [Esc] returns control to your program. ADDTIME - Add two times together Usage - Call AddTime(Time1$, Time2$, TimeSum$) Time1$ Time in HH:MM:SS format (military time) Time2$ Time in HH:MM:SS format (military time) TimeSum Sum of Time1$ and Time2$ in HH:MM:SS format Programming notes: This routine is written in Quickbasic No validation is done, so invalid times (i.e. 99:99:88) will cause unpredictable results. Example: Time1$ = "10:45:00" Time2$ = "22:30:00" Call AddTime$(Time1$, Time2$, TimeSum$) TimeSum$ would equal "09:15:00". This says that 22 and 1/2 hours after 10:45 am puts us at 9:15 am. SUBTIME - Subtract two times Usage - Call SubTime(Time1$, Time2$, TimeDiff$) Time1$ Time in HH:MM:SS format (military time) Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 85 Time2$ Time in HH:MM:SS format (military time) TimeSum Difference of Time1$ and Time2$ in HH:MM:SS format Programming notes: This routine is written in Quickbasic No validation is done, so invalid times (i.e. 99:99:88) will cause unpredictable results. Example: Time1$ = "10:45:00" Time2$ = "22:30:00" Call SubTime$(Time1$, Time2$, TimeSum$) TimeSum$ would equal "12:15:00". This says that 22 and 1/2 hours before 10:45 am puts us at 12:15 pm. Timer Services TIME TICKS BSGETIME Usage - Call BsGeTime(High%, Low%, Days%, OHigh%, OLow%, ODays%) ClTicks = FnTicks(High%, Low%, Days%) ClTime$ = FnTime$(ClTicks) High% High order word of tick count Low% Low order word of tick count Days% Number of days since the clock (or computer) started OHigh% High order word of the tick count last time BsGeTime was called OLow% Low order word of the tick count last time BsGeTime was called ODays% Number of days elapsed since the clock started - last time BsGeTime was called Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 86 ClTicks Number of clock ticks since the computer was started ClTime$ Number of clock ticks converted to time Programming notes: See the program TIMER.BAS in the sample programs as an example. These functions are used primarily to compute the time required to complete a process. Time is accurate to 1/18th of a second. Some TSR software intercept the timer and may cause the clock to slow down. This type of program will invalidate the numbers returned by BsGeTime. BsGeTime is written in Assembly, FnTime$ and FnTicks are functions written in QuickBasic. These routines are found in TIME.FN and TICKS.FN, respectively. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 87 Video Primitives Function Summary PUTLINE - Write a line of text to the video buffer SAVESCR - Copy a window from the video buffer to memory RESTSCR - Restore a window from memory to the video buffer INPWIN - Get input from the keyboard COLORLIN - Change the background color of a line NOTE: As a general rule, you should not use these functions in your programs. The higher level functions described in the following pages should be used in order to maintain maximum compatibility with future releases of QBWARE. One exception is INPWIN. Use this routine for ALL input. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 88 PUTLINE - Write a line of text to the video buffer Usage - Call PutLine(Snow%, Text$, Row%, Col%, Fg%, Bg%) Snow% Display control 1 - Raw display to video RAM 0 - Display to video RAM after retrace Text$ Text to display on the screen Row% Row at which the text should be placed Col% Column at which the text should be placed Fg% Foreground color of the text Bg% Background color of the text. Programming notes: This function has been tested and found to be compatible with MDA, CGA, EGA and VGA in the text modes. IBM-PC hardware compatibility is required. Snow% should always be 1 unless you see some distortion on the screen. This distortion will appear on some of the older IBM CGA cards. It will not appear on EGA, VGA MDA and the newer CGA cards (e.g COMPAQ). Originally, QBWARE provided the ability to print via BIOS for some non-compatibles. This feature was removed becuase it's too darn slow. Col% and Row% should be treated as though they wer part of a locate command (i.e. the upper left corner is col 1, row 1 not col 0, row 0). See Appendix B for color codes. SAVESCR - Copy a window from the video buffer to memory Usage - Call SaveScr(Tr%, Lc%, Br%, Rc%, StackSeg%, StackOff%) Tr% Top row of the area to copy Lc% Left column of the area to copy Br% Bottom row of the area to copy Rc% Right column of the area to copy Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 89 StackSeg% Segment of a far array which will hold the section of the screen StackOff% Offset of a far array which will hold the section of the screen Programming notes: This function allows you to copy a portion of the screen to a far array. The portion of the screen can be restored using RestScr. See WINSTACK.SUB as an example. Use PushWin when saving a screen. StackSeg% and StackOff% should point to the element of a far integer array that will hold the screen. RESTSCR - Restore a window from memory to the video buffer Usage - Call RestScr(Tr%, Lc%, Br%, Rc%, StackSeg%, StackOff%) Tr% Top row of the area to restore Lc% Left column of the area to restore Br% Bottom row of the area to restore Rc% Right column of the area to restore StackSeg% Segment of a far array which holds the section of the screen to restore StackOff% Offset of a far array which holds the section of the screen to restore Programming notes: This function allows you to restore a portion of the screen that was copied to a far array using SaveScr. See WINSTACK.SUB as an example. Use PopWin when restoring a screen. StackSeg% and StackOff% should point to the element of a far integer Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 90 array that holds the screen. INPWIN - Get input from the keyboard Usage - Call InpWin(WinStack%(), Input.Char$, Code%) WinStack%() The window stack Input.Char$ Character retrieved from the keyboard buffer Code% 0 - Return control to the calling program only after a key has been pressed 1 - Return control to the calling program immediately Programming notes: This is a replacement for the QB INKEY function. THIS ROUTINE DISPLAYS THE STATUS BAR AND WILL PLAY A PROMINENT ROLE IN FUTURE RELEASES OF QBWARE. PLEASE USE THIS ROUTINE FOR ALL KEYBOARD INPUT. Using CODE% = 1 causes INPWIN to wait for keyboard input before returning to the calling program. Otherwise, control is returned immediately even if there is no keyboard input. COLORLIN - Change the color of a window Usage - Call ColorLin(Snow%, Tr%, Lc%, Fg%, Bg%, Len%) Snow% Display control 1 - Raw display to video RAM 0 - Display to video RAM after retrace Tr% Top row of the area to color Lc% Left column of the area to color Fg% Foreground color Bg% Background color Len% Length of the line to be re-colored Programming notes: Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 91 See Appendix B for color codes. If Fg% or Bg% is -1, the color will not be changed. This allows you to change only the foreground color or background color by itself. In general do not use this function, use ColorWin. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 92 Window Routines Function Summary PUTWIND - Pop up a window on the screen PUSHWIN - Copy a window from the video buffer to the screen stack POPWIN - Copy a window from the window stack to the video buffer INITWIN - Initialize windowing environment parameters DEFWIN - Define individual window parameters CNGWIN - Change window parameters MOVEWIN - Move a window to a different part of the screen POPTEXT - Display an array of text within a window POPFTEXT - Display a formatted text window COLORWIN - Recolor a window Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 93 PUTWIND - Pop up a window on the screen Usage - Call PutWind(WinHandle%, WinStack%(), Head$) WinHandle% Window handle previously set up with DefWin WinStack%() The window stack Head$ Heading to appear on the top line of the window Programming notes: If the handle has not been previously defined with DefWin, you will get unpredictable results. Read Appendix F for more information on the windowing routines. This function displays a blank window on the screen. The characteristics of the window are defined by the handle. PUSHWIN - Copy a window from the video buffer to the screen stack Usage - Call PushWin(WinHandle%, WinStack%(), WinFrame%() WinPoint%) WinHandle% Window handle previously set up with DefWin WinStack%() The window stack WinFrame%() The window frame definition WinPoint% The window stack pointer Programming notes: This function will copy the window defined by WinHandle% to the screen stack. Using an invalid handle will cause unpredictable results. Read Appendix F for more information on the windowing routines. Use PopWin to restore the window to the screen. POPWIN - Copy a window from the window stack to the video buffer Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 94 Usage - Call PopWin(WinStack%(), WinFrame%() WinPoint%) WinStack%() The window stack WinFrame%() The window frame definition WinPoint% The window stack pointer Programming notes: Read Appendix F for more information on the windowing routines. This function will re-display a window that was previously saved with PushWin. The last window that appeared on the screen will disappear as a result of using this function. If there are no windows on the screen stack (i.e. you haven't used PushWin), unpredictable results will occur. INITWIN - Initialize windowing environment parameters Usage - Call InitWin(WinStack%(), WinFrame%, WinPoint%, MaxWin%, _ ExitKeys$, TabLen%, SBar%, SRow%, SFg%, SBg%, Snow%) WinStack%() The window stack WinFrame%() The window frame definition matrix WinPoint% The window stack pointer MaxWin% The maximum number of windows that can be defined ExitKeys$ A string of scan codes that, when pressed, will cause a window routine to be exited. (See note below) TabLen% Tab length for PopText. SBar% 0 - do not display a status bar 1 - display a status bar SRow% Row where the status bar will be displayed. SFg% Status bar foreground color SBg% Status bar background color Snow% 1 - Write directly to the video buffer Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 95 0 - Write directly to the video buffer after sync with horizontal retrace. Programming notes: This function defines parameters used by all of the other window routines. Always set up the [Esc] key in ExitKeys$ (i.e. ExitKeys$ = Chr$(27)) No other keys will function in this release. Unless you have a good reason, set TabLen% at 8. When displaying the Status bar, put it on line 1 or line 24 for best results. Use Snow% = 0 only for old IBM CGA adapters that show distortion on the screen when the window routines are used. Mono, EGA and VGA should all have Snow% = 1. Snow% = 0 will slow down the display. DEFWIN - Define individual window parameters Usage - Call DefWin(WinHandle%, WinStack%(), Tr%, Lc%, Br%, Rc%, _ Frame%, Fg%, Bg%, Grow%, Shadow%) WinHandle% Window handle previously set up with DefWin WinStack%() The window stack Tr% Top row of the area to color Lc% Left column of the area to color Br% Bottom row of the area to color Rc% Right column of the area to color Frame% Frame description. 0 - No frame 1 - Single line frame 2 - Double line frame Fg% Foreground color Bg% Background color Grow% 0 - Pop the window onto the screen 1 - Make the window appear to grow onto the screen Shadow% 0 - No shadow Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 96 1 - Shadow the window to provide a 3-D effect Programming notes: Any changes made here will not take effect until the next window operation takes place (i.e. - If this handle is already displayed on the screen, changing the background color from Blue to Red using CngWin has no immediate effect. You must re-display the window or use ColorWin). Read Appendix F for more information on the windowing routines. CNGWIN - Change window parameters Usage - Call CngWin(WinHandle%, WinStack%(), Tr%, Lc%, Br%, Rc%, _ Frame%, Fg%, Bg%, Grow%, Shadow%) WinHandle% Window handle previously set up with DefWin WinStack%() The window stack Tr% Top row of the area to color Lc% Left column of the area to color Br% Bottom row of the area to color Rc% Right column of the area to color Frame% Frame description. 0 - No frame 1 - Single line frame 2 - Double line frame Fg% Foreground color Bg% Background color Grow% 0 - Pop the window onto the screen 1 - Make the window appear to grow onto the screen Shadow% 0 - No shadow 1 - Shadow the window to provide a 3-D effect Programming notes: Any changes made here will not take effect until the next window operation takes place (i.e. - If this handle is already displayed on the screen, changing the background color from Blue to Red using CngWin has no immediate effect. You must re-display the window or Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 97 use ColorWin). Read Appendix f for more information on the windowing routines. MOVEWIN - Move a window to a different part of the screen Usage - Call MoveWin(WinHandle%, WinStack%(), WinPoint%, Tr%, Lc%) WinHandle% Not currently used WinStack%() The window stack WinPoint% The window stack pointer Tr% Top row of the new window location Lc% Left column of the new window location Programming notes: This function immediately moves the current window to the coordinates indicated by Tr% and Lc%. No re-sizing is done. If there is no current window, unpredictable results will occur. POPTEXT - Display an array of text within a window Usage - Call PopText(WinHandle%, WinStack%(), WinFrame%(), WinPoint%,_ Text$()) WinHandle% Not currently used WinStack%() The window stack WinFrame%() The window frame definition matrix WinPoint% The window stack pointer Text$() Array of text to be displayed in the window Programming Notes: This function will display the text in Text$() within the window defined by WinHandle%. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 98 The window is automatically sized, that is, if an entry in Text$() is too wide to fit in the window or if there are more lines in Text$() than in the window, PopText automatically makes it fit and allows you to use cursor control keys to display the entire array. See Appendix F for more information about cursor control while a PopText window is being displayed. If Text$() is empty, unpredictable results will occur. Press a key defined in ExitKeys$ when InitWin was executed, to exit PopText (press [Esc]). POPFTEXT - Display a formatted text window Usage - Call PopFText(WinHandle%, WinStack%(), WinFrame%(), WinPoint%,_ Location%(), TLength%(), TColors%(), Text$()) WinHandle% Not currently used WinStack%() The window stack WinFrame%() The window frame definition matrix WinPoint% The window stack pointer Location%() Two dimensional array containing the row and column where each data item will be placed. Row and column should be relative to the upper left corner of the window. TLength%() One dimensional array containing the length of each item to display. TColors%() Two dimensional array containing the foreground and background color of each item to display. Text$() Array of text to be displayed in the window Programming Notes: This function will display formatted text in the current window. Press a key defined in ExitKeys$ when InitWin was executed, to exit PopFText (press [Esc]) Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 99 Remember, Location%() is relative to the upper left corner of the current window. If TColors%() is 0, then the colors used will be the default window colors. COLORWIN - Recolor a window Usage - Call ColorWin(Fg%, Bg%) Fg% New foreground color Bg% New background color Programming Notes: This function changes the foreground and background of the current window. The new colors affect only the window onscreen. If the same handle is used again, the old colors will be used. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 100 Input Routines Function Summary INCHAR - Accept input of a string of characters INDATE - Accept date input INYES - Accept yes/no input INMF - Accept male/female input Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 101 INCHAR - Accept input of a string of characters Usage - Call InChar(WinHandle%, WinStack%(), WinFrame%(), Row%, Col% _ Fg%, Bg%, Pic$, Init$, ExitLst$, InputText$, Lstchr$) WinHandle% Not currently used WinStack%() The window stack WinFrame%() The window frame definition matrix Row% Starting Row (Relative to the current window) Col% Starting Column Fg% Foreground color Bg% Background color Pic$ Picture definition of the input field Init$ Initial value of the input field ExitLst$ List of keys that, when pressed, will cause control to be returned to the calling program InputText$ The field returned to the calling program that contains the input. LstChr$ The last character entered. Programming notes: Init$ will be initially displayed by the input routine. (See next page) Pic$ describes the input field thru the use of a mask. The valid characters in Pic$ are: U - Indicates this character will be translated to upper case L - Indicates this character will be translated to lower case X - Indicates no translation Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 102 8 - Indicates only numerics will be accepted in this character. 9 - Indicates only numerics and blanks will be accepted. Any other character will be displayed and input will not be allowed in that character. For example, when inputting Social Security Numbers, a mask of "888-88-8888" will require a number wherever an '8' appears and will not allow input wherever a '-' appears. Row% and Col% are always relative to the upper left corner of the current window. Generally, it is a good idea to use only [Esc] and F1-F10 in ExitLst$. When the end of the field is reached, control returns to the calling program. See Appendix F for a description of cursor control. Depressing [Ins] will toggle insert mode off/on. Backspace is destructive - that is, any character that you backspace over is erased. InChar, like all of the input routines, will maintain the status bar if it is being displayed. INDATE - Accept date input Usage - Call InDate(WinHandle%, WinStack%(), WinFrame%(), Row%, Col% _ Fg%, Bg%, Pic$, Init$, ExitLst$, InputText$, Lstchr$) WinHandle% Not currently used WinStack%() The window stack WinFrame%() The window frame definition matrix Row% Starting Row (Relative to the current window) Col% Starting Column Fg% Foreground color Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 103 Bg% Background color Pic$ Not currently used Init$ Initial value of the input field ExitLst$ List of keys that, when pressed, will cause control to be returned to the calling program InputText$ The field returned to the calling program that contains the input. LstChr$ The last character entered. Programming notes: This subroutine will accept a valid date in MM/DD/YY format. Row% and Col% are always relative to the current window. Generally, it is a good idea to use only [Esc] and F1-F10 in ExitLst$. When the end of the field is reached, control returns to the calling program. See Appendix F for a description of cursor control. INYES - Accept yes/no input Usage - Call InYes(WinHandle%, WinStack%(), WinFrame%(), Row%, Col% _ Fg%, Bg%, Pic$, Init$, ExitLst$, InputText$, Lstchr$) WinHandle% Not currently used WinStack%() The window stack WinFrame%() The window frame definition matrix Row% Starting Row (Relative to the current window) Col% Starting Column Fg% Foreground color Bg% Background color Pic$ Not currently used Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 104 Init$ Initial value of the input field ExitLst$ List of keys that, when pressed, will cause control to be returned to the calling program InputText$ The field returned to the calling program that contains the input. LstChr$ The last character entered. Programming notes: This routine will accept only a Yes/No input. Row% and Col% are always relative to the current window. Generally, it is a good idea to use only [Esc] and F1-F10 in ExitLst$. When the end of the field is reached, control returns to the calling program. See Appendix F for a description of cursor control. INMF - Accept male/female input Usage - Call InMF(WinHandle%, WinStack%(), WinFrame%(), Row%, Col% _ Fg%, Bg%, Pic$, Init$, ExitLst$, InputText$, Lstchr$) WinHandle% Not currently used WinStack%() The window stack WinFrame%() The window frame definition matrix Row% Starting Row (Relative to the current window) Col% Starting Column Fg% Foreground color Bg% Background color Pic$ Not currently used Init$ Initial value of the input field ExitLst$ List of keys that, when pressed, will cause control to be returned to the calling program Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 105 InputText$ The field returned to the calling program that contains the input. LstChr$ The last character entered. Programming notes: This routine will accept only a Male/Female input. Row% and Col% are always relative to the current window. Generally, it is a good idea to use only [Esc] and F1-F10 in ExitLst$. When the end of the field is reached, control returns to the calling program. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 106 Menu Routines Function Summary BARMENU - Provide a two line bar menu BARMENU1 - Multi-line bar menu BARMENU2 - Lotus-like bar menu PULLDOWN - Display a pulldown menu SCRLSLCT - Display a scrollable list of items for selection Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 107 BARMENU - Provide a two line bar menu Usage - Call BarMenu(MenuList$(), Tr%, Fg%, Bg%, Snow%, RtnItm%) MenuList$() An array of items that will be displayed as a menu Tr% The top row of the displayed menu Fg% Foreground color of menu items Bg% Background color of the menu Snow% 1 - Write directly to video RAM 0 - Write directly to video RAM but wait for retrace to eliminate snow. RtnItm% Integer returned to the calling program. This number is the array element that was selected. Programming notes: This function displays a two-line bar menu listing each selection two spaces apart across each line. An inverse bar is placed over the currently selected item. The bar can be moved by using the arrow keys. Selection is made by pressing [Enter] or pressing the first letter of a menu item. Try to make each item start with a different letter. Tr% should be either 1 or 23. Using any other values will place the menu in the middle of the screen. BARMENU1 - Multi-line bar menu Usage - Call BarMenu1(WinHandle%, WinStack%(), WinFrame%(), WinPoint% _ TblData$(), Answer%) WinHandle% Not currently used WinStack%() The window stack WinFrame%() The window frame definition matrix WinPoint% The window stack pointer TblData$() Array of items to be displayed in the menu. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 108 Answer% Integer returned to the calling program. This number is the array element that was selected. Programming notes: This subroutine displays the menu items in a vertical bar menu in the current window. An inverse bar is placed over the currently selected item. The bar can be moved by pressing the arrow keys or [Home] or [End]. Pressing the first letter of a menu selection move the bar to that item. Pressing the [Space] bar selects an item. Sorting the menu items (using PeSort), provides a more professional output. BARMENU2 - Lotus-like bar menu Usage - Call BarMenu2(MenuList$(), Header$,Tr%, Fg%, Bg%, Snow%, RtnItm%) MenuList$() An array of items that will be displayed as a menu Header$ Descriptive text that will appear with the menu Tr% The top row of the displayed menu Fg% Foreground color of menu items Bg% Background color of the menu Snow% 1 - Write directly to video RAM 0 - Write directly to video RAM but wait for retrace to eliminate snow. RtnItm% Integer returned to the calling program. This number is the array element that was selected. Programming notes: This function displays a one-line bar menu listing each selection two spaces apart across each line. An inverse bar is placed over the currently selected item. The bar can be moved by using the arrow keys. Selection is made by pressing [Enter] or pressing the first letter of a menu item. Try to make each item start with a different letter. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 109 Tr% should be either 1 or 23. Using any other values will place the menu in the middle of the screen. PULLDOWN - Display a pulldown menu Usage - Call PullDown(WinStack%(), WinFrame%(), WinPoint%, MenuList$()_ Start%, Tr%, Fg%, Bg%, MFg%, BFg%, RtnMnu%, RtnItm%) WinStack%() The window stack WinFrame%() The window frame definition matrix WinPoint% The window stack pointer MenuList$() Two-dimensional array of items to be displayed in the menu. Start% Starting menu to display Tr% The top row of the displayed menu Fg% Foreground color of menu bar Bg% Background color of the menu bar MFg% Foreground color of menu items MBg% Background color of the menu RtnMnu% Co-ordinates (array element numbers) of the item RtnItm% selected. Programming notes: Just like the QuickBasic menuing system. SCRLSLCT - Display a scrollable list of items for selection Usage - Call ScrlSlct(WinHandle%, WinStack%(), WinFrame%(), WinPoint%, _ TblData$(), TblSlct%()) WinHandle% Not currently used WinStack%() The window stack WinFrame%() The window frame definition matrix WinPoint% The window stack pointer Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 110 TblData$() One-dimensional array of items to be displayed in the menu. TblSlct%() One-dimensional array with the same number of elements as TblData$(). Each item should be initialized to 0. On return from ScrlSlct, each selected item will contain a -1 in its corresponding TblSlct% element. Programming notes: Items are displayed in the current window, so make sure it is wide enough to accommodate the longest item. The current item will have an inverse bar over it. It may be selected by pressing the [Space] bar. Normal cursor control keys will move the bar. Additionally, pressing [Home] and [End] will position the bar over the first and last items in the list. Pressing the first letter of an item will position the bar over that item. When an item is selected, a block will appear to the left of the item. If the list is to deep for the current window, [PgDn] and [PgUp] will place more items in the window. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 111 Miscellaneous Routines Function Summary PESORT - Sort a character array FNMODULO - Find the modulus of a large number QBCHIP - Determine Processor and Co-Processor type Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 112 PESORT - Sort a character array Usage - Call PeSort(List$(), Count%, Startpos%, SortLen%) List$() One dimensional array of character items to sort Count% Number of elements to sort Startpos% Starting position, relative to 1, of the sort key SortLen% Length of the sort key Programming notes: PeSort performs a partition-exchange sort that provides excellent speed for all sizes of arrays. FNMODULO - Find the modulus of a large number Usage - Wrk.Mod = FnModulo(Target, Divisor) Wrk.Mod Modulus of Target and Divisor (single precision) Target Number for which you wish to find the Mod Divisor What else - the divisor Programming notes: This function will find the modulus for large numbers. It's not terribly efficient but it does work and can easily be adapted for double precision numbers. QBCHIP - Determine Processor and Co-Processor type Usage - CALL QbChip(ProcTyp%, NDP%) ProcTyp% Processor type 20 - NEC V20/V30 86 - 8086/8088 186 - 80186 286 - 80286 386 - 80386 486 - 80486 Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 113 NDP% Co-Processor type 0 - no Co-Processor found 87 - 8087 287 - 80287 387 - 80387 Programming notes: The 486 chip has a built in math co-processor. The method used to detect the presence of a 486 processor will not work while some protected mode programs are running (i.e. Windows). Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 114 Appendices Appendix A Keyboard Scan Codes Decimal Character 3 NUL 15 Shft-tab 16-25 Alt+(Q,W,E,R,T,Y,U,I,O,P) 30-38 Alt+(A,S,D,F,G,H,J,K,L) 44-50 Alt+(Z,X,C,V,B,N,M) 59,68 F1-F10 71 Home 72 Up cursor 73 PgUp 75 Left cursor 77 Right cursor 79 End 80 Down cursor 81 PgDn 82 Ins 83 Del 84-93 Shft-(F1-F10) 94-103 Ctrl-(F1-F10) 104-113 Alt+(F1-F10) 114 PrtSc 115 Left cursor 116 Right cursor 117 End 118 PgDn 119 Home 120-131 Alt+(1,2,3,4,5,6,7,8,9,0,-,=) 132 PgUp Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 115 Appendix B BASIC Colors Color code Color 0 Black 1 Blue 2 Green 3 Cyan 4 Red 5 Magenta 6 Brown 7 White 8 Gray 9 Light Blue 10 Light Green 11 Light Cyan 12 Light Red 13 Light Magenta 14 Yellow 15 High-Intensity White Notes: The only valid background colors are 0-7. Add 16 (sixteen) to the color to cause blinking. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 116 Appendix C About Disks and Diskettes DISK AND DISK FORMATS Hard disks and floppy disks essentially use the same format under DOS. There are four logical areas of interest on each disk - the boot sector, the FAT, the root directory and the data area. Physically, data is recorded on a series of tracks. Each track is further divided into areas called sectors. The physical capacity of each disk varies considerably from drive to drive. There are only two characteristics of disks that are fixed by hardware constraints - the number of sides and the location of each track on the disk. The size and number of sectors and their location within each track is totally under software control. Each of these characteristics is defined by the formatting software (the FORMAT program usually). We'll discuss most of the DOS formats shortly. Sectors can be placed on a track in any order and in any combination of 4 sizes - 128, 256, 512 or 1024 bytes. Generally it is wise to use a sector size of 512 bytes because that's the standard and there are probably many programs, including DOS, that depend on a 512 byte sector size. There are several standard formats currently used by DOS. The following table summarizes each format and it's characteristics. Type Sides Sectors Tracks Bytes SSDD-8 1 8 40 160,000 DSDD-8 2 8 40 320,000 SSDD-9 1 9 40 180,000 DSDD-9 2 9 40 360,000 3 1/2 in. 2 9 80 720,000 DDHD 2 15 80 1,200,000 The most common of these formats is the DSDD-9, but with the introduction of laptops and the PS/2 line from IBM, the 3 1/2 in. diskettes will probably become the standard of the future. When using the BIOS to access disks, it is important to understand their characteristics. Bios disk access routines require us to know three things about the particular sector that we're looking for. These are the track number, the cylinder number, and the sector number, The first track on a disk is always 0. Diskettes with 40 tracks will have them numbered 0 - 39. The cylinder number is sometimes called the side or head number. It really represents which side of the diskette we want to read, top or bottom. Cylinder is 0 for top or 1 for bottom. Hard disks may have more than two cylinders. Sector numbers always start with Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 117 1. Therefore, the first sector on a disk is always Track 0, Cylinder 0, Sector 1. As I said earlier, DOS organizes the disk into four areas. We'll examine each of these separately. The Boot Sector The boot sector contains a short program used to start the computer and it also contains the characteristics of the disk in an area called the BIOS parameter block. The short program does one of two things - it loads the three startup modules, IBMBIO.COM, IBMDOS.COM, and COMMAND.COM and transfers control to COMMAND.COM or it displays a message stating that the diskette is not a bootable one. The format of the boot sector is as follows: Location Description 0-2 Branch to first byte of boot code 3-29 BIOS parameter block 3-10 System ID 11-12 Number of bytes/sector 13 Number of sectors/cluster 14-15 Number of reserved sectors at beginning 16 Number of FAT's 17-18 Number of root directory entries 19-20 Total number of sectors on disk 21 Format ID 22-23 Number of sectors/FAT 24-25 Number of sectors/track 26-27 Number of cylinders 28-29 Number of special reserved sectors The rest of the boot program follows the BIOS parameter block. At the end of the boot record, we need the two-byte signature, a hex 55AA. The Root Directory The directory holds basic information about each file. There can, of course, be more than one directory, but there is only one root directory. Subdirectories have essentially the same format as the root directory, but there is one notable difference. A subdirectory is really another file - a special type of file. As a file, it can grow to virtually any size and have any number of entries (not totally true, but there are no PRACTICAL limits). The root directory is fixed in length and therefore can have only a limited number of entries. This is usually 64 or 112. Each Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 118 entry in the directory uses 32 bytes, so we are limited to sixteen entries per sector. Each entry contains the following eight fields: Position Description 0-7 Filename 8-10 Filename extension 11 Attribute 12-21 Reserved 22-23 Last update time 24-25 Last update date 26-27 First FAT entry 28-31 File size The Data Area The data area is the largest area on the disk. It is where our files are actually placed. Space is allocated in units called clusters. A cluster is made up of one or more sectors. This is defined at disk format time. That is all we need to know about the data area. THE FAT The FAT - file allocation table - keeps track of where our files physically reside on disk. The directory entry for each file contains the address of the first sector that the file occupies. If the file occupies more than 1 sector, DOS keeps track of it in the FAT. There are generally two copies of the FAT on every disk. DOS updates both copies, but only uses one of them for file retrieval. FAT's have one of two formats - a 12 bit or a 16 bit format. The 12 bit format allows you to access just over 4,000 clusters, so it is used primarily in diskettes and the smaller hard disks. The 16 bit format allows us to access many more clusters and facilitate larger hard disks. It is because of the FAT entry size that we are limited, by DOS, to a maximum 32 Meg hard disk (although there are several programs, such as SPEEDSTOR by Storage Dimensions, Inc. that do away with this limitation and in fact, some versions of DOS 3.3x also provide work-arounds for this limit - the most notable being COMPAQ DOS 3.31). DOS V4.00 is the first general release of DOS that eliminates this limitation. Each byte in the FAT represents a cluster and tells us the disposition of that cluster. The first two bytes in the FAT are reserved and are not used for this purpose. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 119 For illustration, we will use a 12 bit FAT. The allowable values in each entry are: Value Description 0 The cluster is unused and available for use 1-FF0(4080) A pointer to the next cluster that this file occupies. FF7(4087) The cluster has been flagged as unusable by FORMAT. This occurs when the format program cannot successfully write to one of the sectors in the cluster. FFE(4094) The cluster is not used but is unavailable for use. This occurs only when DOS reserves a cluster. FFF(4095) This indicates that this is the last cluster that a file occupies. As you can see, the FAT links together the clusters that make up a file. It is also easy to see that if the FAT becomes damaged, your disk or diskette becomes so much trash. In general, it's not a good idea to manipulate the FAT unless your an experienced programmer. FORMATTING A DISKETTE Please keep in mind that these procedures are directed to a floppy disk only. In principle, formatting a hard disk is similar, but don't try it with these guidelines. Formatting a diskette is a four-step process. 1 Format each track of the diskette 2 Write the boot sector 3 Initialize the FAT 4 Initialize the root directory We can format each track of a diskette using the BsDFmt service provided in QBWARE. Note that this service requires the use of a 'track format table'. This table contains a 4-bytes descriptor for each sector being formatted. Individual sectors cannot be formatted. You must format an entire track with one BIOS call but the track format table lets us define the characteristics of each sector. The track format table looks like this: Byte 1 - track being formatted Byte 2 - Head being formatted Byte 3 - Sector being formatted Byte 4 - size code Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 120 The size code has the following values: 0 128 byte sectors 1 256 byte sectors 2 512 byte sectors 3 1024 byte sectors QBFORMAT.BAS is included with the sample programs as an example of Diskette formatting. It does work, however, it doesn't do any error checking. COPY PROTECTION Using the BIOS format service, we can devise our own copy protection schemes. These schemes are not as elaborate as the schemes used by some of the larger software houses (these actually use special hardware to put junk in places on a diskette that are read-only accessible to a standard floppy controller), but can be effective against the casual software pirate. The means available to us are: - leave out a sector number in the track format table - place a unique number in the track format table - format ten sectors on one or more tracks - change the sizes of one or more sectors on a track - format past track 39 - change the interleave Be careful, not all of these techniques work consistently with all floppy disk controllers. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 121 APPENDIX D Using the File Access Services All of the file access services use the DOS extended file services. These services call for the use of file handles - a UNIX concept. Because of this we are still limited to a maximum of 20 open files in any Quickbasic program. This includes the 5 standard files that DOS requires effectively limiting any Quickbasic program to 15 open files at any one time. This should normally be enough, however, if it becomes a problem, there are some facilities in QBWARE that will allow you to open more than 15 files, but still we cannot exceed 20. If you must have more than 20 open files, you must use the old FCB style file services. This will allow you to access up to 255 files simultaneously. These routines are available from AJM Software and if you'd like them, just write (Note: DOS 3.3 will allow 255 open files, so, that's you're best bet). Using the file access services requires the use of an ASCIIZ string. This is simply a file name (or part of a file name) followed by a null. Some examples of ASCIIZ strings: FlSpec$ = "C:COMMAND.COM" + Chr$(0) Path$ = "\QUICKBAS" + Chr$(0) The standard error codes for all of the QBWARE file management routines except FLRSECT and FLWSECT are as follows: Code Reason 0 service completed successfully 1 invalid request 2 file not found or path invalid 3 path not found 4 no handle available 5 access denied 6 invalid handle 12 invalid access code 15 invalid drive specification 17 not the same device (FLMOVE only) 18 no matching directory entry found 22 attempt to delete current directory 80 file already exists 255 invalid parameter Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 122 Appendix E The Print Spooler Version 3.00 of DOS brought with it a remarkable new program - the print spooler. The spooler is remarkable because it allows you to print files in the background while the computer is free to do other tasks. It is somewhat limited in that it does automatically capture data going to the printer and spool it for you and it must be used from the DOS prompt. In order to use it, you must write your report to a file and subsequently go to the DOS prompt and submit it to the print queue - either manually or through a batch file. The services provided in QBWARE will assist in incorporating the spooler into any Quickbasic application. You must still write each report to a file, but we can, with DOSPSUB, submit the file to the print queue directly from a Quickbasic program. In order to use QBWARE spooler service, we must start the spooler before your Quickbasic basic program executes. The spooler can be started from the DOS prompt or from your AUTOEXEC.BAT file (any BAT file will do). The spooler program is called PRINT.EXE and is available on your DOS version 3.XX diskettes. When starting the spooler, there are several options that can be used. These are: /D Device that all files will be printed on - if omitted, the spooler will prompt you for a device name /Q Maximum number of files that can be in the print queue - the default is 4 and the absolute maximum that can be used is 32 /B Buffersize of the internal buffer used by the spooler - the default is 512 bytes - we always use 2048 bytes, but the correct value will depend on overall system usage /S Timeslice for the spooler - this defines the number of clock ticks that the spooler will use - the default is 8 and the values can range from 1-255 /M Specifies the maximum number of clockticks that the spooler will use to print a character - values can be 1-255 and the default is 2 /U Specifies the number of clockticks that the spooler Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 123 will wait for the printer to become available - values can range from 1-255 and the default is 1 The command PRINT /D:LPT1 /B:2048 /Q:32 will activate the spooler with an internal buffer of 2048 bytes and cause all output to be spooled to LPT1. The maximum number of files that can be in the queue at one time is 32. Once this is completed, the routines in QBWARE can be used. Return codes from the spooler are as follows: Rc Reason 0 Successful 1 Spooler inactive 2 Spooler inactive (DOSPSTAT only) 2 File not found 3 Path not found 4 Too many open files 5 Access denied 8 Queue full 9 Spooler busy 12 Name too long 15 Invalid drive 255 Invalid DOS version Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 124 Appendix F QBWARE Windowing Routines These are some general notes about the windowing routines. Most of the routines are written in QuickBasic so they can be easily modified to suit individual needs. There are a few Assembler routines, but they are low-level and hopefully will not need modification. The windowing routines have been tested with MDA, CGA, EGA and VGA adapters. THEY ARE DESIGNED TO FUNCTION IN THE TEXT MODES ONLY. They have not been checked out on Hercules mono graphics so I don't know what will happen if you use the routine on that hardware - but I suspect they won't work. First, a little terminology: WINDOW STACK This is an integer array where some general information is kept about the windowing environment such as whether to display a status bar, what color status bar, etc. It's main function, however, is to store screen images that are being overlayed by windows. This enables the windowing to quickly popup a window on the screen and subsequently remove it - leaving the screen underneath intact. All of the sample programs use an array of 20000 elements. One character will fit in each element and an array of this size will allow us to store 10 entire screens. Most windows will be significantly smaller than an entire screen, so 20000 should be large enough for almost all applications. It is critical that the array is allocated dynamically. This insures that QuickBasic will place it in the far heap and out of your current data segment which is limited to 64K. WINDOW FRAME The window frame is a two-dimensional array that allows us to predefine window co-ordinates and assign a handle to them. WINDOW POINTER The window pointer maintains the current stack position. It simply points to the next empty slot in the stack. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 125 The fields mentioned above are crucial to the operation of the windowing system. DO NOT directly access these fields. They should be changed only by the windowing routines. In general, you move around most of the windows using the normal cursor control keys. These are: [RightArrow] [LeftArrow] [UpArrow] [DownArrow] [BackSpace] [Home] [End] [Tab] [PgUp] [PgDn] [Ins] (Data entry only) [Del] (Data entry only) Some of these do not apply to all windowing or menu routines. You can get a feel for them by running the DEMO program or the sample programs and experimenting. None of the routines contain extensive bounds or format checking so passing an empty array or coordinates that don't make sense (i.e. row 40 and column 122) can and will generally cause an illegal function call or funny looking display. Overrunning the window stack will generally cause your machine to lock up. You overrun the stack when the space allocated is not sufficient to hold all of the windows that have been copied into the stack. The routine PushWin puts a window into the stack and the routine PopWin removes it from the stack and frees up the stack space. If you have any problems, look at the DEMO and sample programs. Most of the routines are used there. If you still need help, feel free to call. Copyright (c) AJM Software 1987, 1991 All Rights Reserved Page 126 ----------------end-of-author's-documentation--------------- Software Library Information: This disk copy provided as a service of Public (software) Library We are not the authors of this program, nor are we associated with the author in any way other than as a distributor of the program in accordance with the author's terms of distribution. Please direct shareware payments and specific questions about this program to the author of the program, whose name appears elsewhere in this documentation. If you have trouble getting in touch with the author, we will do whatever we can to help you with your questions. All programs have been tested and do run. To report problems, please use the form that is in the file PROBLEM.DOC on many of our disks or in other written for- mat with screen printouts, if possible. PsL cannot debug pro- programs over the telephone, though we can answer questions. Disks in the PsL are updated monthly, so if you did not get this disk directly from the PsL, you should be aware that the files in this set may no longer be the current versions. Also, if you got this disk from another vendor and are having prob- lems, be aware that some files may have become corrupted or lost by that vendor. Get a current, working disk from PsL. For a copy of the latest monthly software library newsletter and a list of the 2,000+ disks in the library, call or write Public (software) Library P.O.Box 35705 - F Houston, TX 77235-5705 1-800-2424-PSL MC/Visa/AmEx/Discover Outside of U.S. or in Texas or for general information, Call 1-713-524-6394 PsL also has an outstanding catalog for the Macintosh.